components

Catálogo de componentes reutilizáveis e renderizáveis (react/html/embed) com schemas de props e props padrão, agrupados em categorias e posicionados nas regiões de layout de página.

Caminho de origem: libraries/cms/src/cms-component.controller.ts, cms-component.service.ts

Arquivo do módulo: cms.module.ts

Introdução

O submódulo Components gerencia `cms_component`, o catálogo de blocos de construção que o endpoint `saveComponents` do submódulo Pages instancia nas regiões de layout de uma página. Cada componente pertence a exatamente uma categoria (`category_id`, FK para `cms_component_category`, `onDelete: RESTRICT`), tem um `type` (react, html ou embed — padrão react), um `props_schema` opcional que descreve o formato de suas props configuráveis para a geração de formulários do editor administrativo, um objeto `default_props` opcional aplicado quando uma nova instância é criada, um flag `is_active`, um flag `is_system` e uma `order` usada para ordenação dentro de sua categoria. `GET /cms/components` aceita um filtro opcional de query `category_id` e sempre ordena por categoria e, em seguida, por order.

A criação e a atualização seguem o mesmo padrão de linha-base-e-depois-upsert-de-locale dos Layouts. `PATCH /cms/components/:id`, no entanto, tem um comportamento não óbvio que vale destacar explicitamente: `CmsComponentService.update()` calcula `hasExplicitFields` — verdadeiro se o corpo da requisição definir qualquer um de `category_id`, `slug`, `type`, `props_schema`, `default_props`, `is_system`, `order` ou `locale`. Se o corpo do PATCH **não** contiver nenhum deles (ou seja, um payload `{}` genuinamente vazio, sem `is_active` também), o serviço trata a chamada como um atalho de alternância e inverte `is_active` para o oposto de seu valor atual. Qualquer corpo que inclua ao menos o mapa `locale` — o caso comum de uma edição apenas de tradução — é tratado como "explícito" e não dispara a alternância, de modo que isso só ocorre com um corpo de requisição verdadeiramente vazio; não é algo que um cliente normal de edição de locale acionaria por acidente, mas significa que um PATCH vazio não é um no-op.

O flag `is_system` existe no schema e no DTO para marcar componentes internos, não deletáveis, mas `CmsComponentService` atualmente não o impõe em lugar nenhum — `delete()` e `update()` se aplicam a componentes de sistema exatamente como a qualquer outro, de modo que proteger componentes internos de edições ou exclusões acidentais não é algo que este endpoint garanta hoje. Separadamente, a tabela `cms_component` define uma coluna `preview_image_file_id` (FK para `file`, `onDelete: SET NULL`) que não tem campo correspondente em `CmsComponentDto` e nunca é lida nem escrita pelo serviço — uma imagem de pré-visualização não pode ser definida por esta API atualmente, apesar de a coluna existir no schema.

Como nos Layouts, todo endpoint de escrita (criar, atualizar, excluir) é restrito a `admin`/`admin-cms`; `cms-editor` e `cms-publisher` podem ler o catálogo para escolher componentes ao construir uma página, mas não podem adicioná-los nem modificá-los.

Endpoints HTTP

5 endpoints

Listagem completa de componentes (não paginada), ordenada por categoria e, em seguida, por order, localizada para o locale da requisição.

Query: category_id? — filter to components in a single category

Cria um novo componente e suas linhas de nome/descrição por locale.

Body

Field	Type	Required	Notes
category_id	number	yes	—
slug	string	yes	—
type	CmsComponentType (react \| html \| embed)	no	Default: react
props_schema	object	no	Describes configurable props for admin form generation
default_props	object	no	Applied to new instances of this component
is_active	boolean	no	Default: true
is_system	boolean	no	Default: false. Not currently enforced by the service
order	number	no	Default: 0
locale	Record<string, { name: string; description?: string }>	yes	e.g. { "en": { "name": "...", "description": "..." } } — upserts one locale row per key

Obtém um único componente, localizado para o locale da requisição.

Params: id (int)

Atualiza um componente (mesmos campos da criação, todos opcionais). Se o corpo da requisição estiver completamente vazio (sem nenhum campo, incluindo locale), o serviço alterna is_active em vez de não fazer nada.

Params: id (int)

Exclui fisicamente um componente. Não protegido contra is_system, nem protegido contra componentes ainda posicionados como instâncias de componente em páginas.

Params: id (int)