Mini site de documentaçãoDeveloper Atlas

Entrada rápida para navegar arquitetura, APIs, operação e guias técnicos do projeto sem depender da estrutura do repositório.

44 notas

Procure por módulo, API, rota, fluxo operacional ou termo do projeto.

Base do projeto/docs/blog-operacao

Blog - Operação

O blog é a camada editorial do ecossistema.

Recorte da seçãoBase estrutural do projeto

Nota de referência para contratos, arquitetura, runbook e organização do workspace. É a camada mais estável da documentação.

Atualizado19 de mar. de 2026
Seções18
Tags4
blogecommerceecommpaneleditorial

Papel do módulo

O blog é a camada editorial do ecossistema.

Ele fica no meio do caminho entre o EcommPanel e o E-commerce:

  • o painel cria, edita, publica e modera;
  • o storefront lista e renderiza os posts publicados;
  • comentários e reações vivem como camada separada de interação.

O que já existe hoje

  • listagem pública em /e-commerce/blog;
  • página de post em /e-commerce/blog/[slug];
  • schema BlogPosting no detalhe;
  • comentários públicos com moderação opcional;
  • reações like e dislike;
  • favorito local no navegador;
  • copiar link;
  • gestão no painel em /ecommpanel/admin/blog;
  • editor e moderação em /ecommpanel/admin/blog/editor.

Como o domínio foi dividido

O blog não foi encaixado dentro do builder genérico de páginas.

Ele nasceu como domínio próprio.

Isso é importante porque o módulo já precisa lidar com:

  • identidade de post;
  • publicação por slug;
  • comentários;
  • reações;
  • separação entre autor, editor, publicador e moderador.

Persistência administrativa

Persistência atual do domínio:

  • PostgreSQL, quando o runtime do painel estiver disponível;
  • JSON local como fallback e como artefato de publicação.

Leitura prática:

  • o admin e as APIs agora preferem o banco;
  • se o banco não estiver acessível, o módulo continua operando com os arquivos locais;
  • quando o banco estiver vazio, o módulo consegue semear a base a partir dos arquivos já existentes.

Arquivos de apoio que continuam existindo:

  • src/data/ecommpanel/blog/posts-index.json
  • src/data/ecommpanel/blog/posts/<postId>.json

Modos de persistência

O blog agora aceita três modos de operação por ambiente:

  • files: usa apenas JSON local e runtime publicado;
  • hybrid: prefere PostgreSQL, mas ainda pode cair para arquivos e semear o banco a partir deles;
  • database: usa apenas PostgreSQL e ignora os arquivos como fonte de runtime.

Variável de controle:

bash
ECOM_BLOG_PERSISTENCE_MODE=hybrid

Leitura prática:

  • desenvolvimento offline: files
  • transição gradual para banco: hybrid
  • operação consolidada em banco: database

Persistência publicada e fallback

Artefatos consumidos pelo storefront:

  • src/data/site-runtime/blog/posts-index.published.json
  • src/data/site-runtime/blog/posts/<slug>.published.json
  • src/data/site-runtime/blog/comments/<slug>.json
  • src/data/site-runtime/blog/reactions/<slug>.json

Esses arquivos continuam importantes por dois motivos:

  • funcionam como fallback operacional;
  • preservam uma camada publicada leve, mesmo com o domínio já lendo do banco quando disponível.

Comportamento de publicação

No painel

  • Salvar rascunho: atualiza o documento administrativo.
  • Salvar e publicar: atualiza o documento administrativo e regenera o runtime por slug.
  • Rascunho: tira o post do runtime publicado sem apagar o documento de origem.
  • o editor também pode vincular o owner editorial do post a um usuário já existente no painel.

No storefront

  • a listagem e o detalhe agora preferem leitura em PostgreSQL;
  • comentários e reações também preferem PostgreSQL;
  • quando o banco não estiver disponível, o módulo cai para os artefatos publicados em arquivo.

Permissões atuais

Permissões relevantes do domínio:

  • blog.posts.create
  • blog.posts.edit
  • blog.posts.publish
  • blog.comments.moderate
  • blog.authors.manage
  • blog.posts.manage como compatibilidade ampla

Papéis editoriais disponíveis:

  • content_author
  • content_editor
  • content_publisher
  • comment_moderator
  • site_editor continua podendo operar o módulo de forma ampla

O post agora também guarda governança editorial:

  • owner;
  • último editor;
  • responsável pela publicação.

Interações públicas

Comentários

  • endpoint: GET/POST /api/blog/posts/[slug]/comments
  • podem ser publicados diretamente ou entrar em moderação;
  • o storefront mostra só comentários aprovados.

Reações

  • endpoint: GET/POST /api/blog/posts/[slug]/reactions
  • valores aceitos: like, dislike e clear;
  • o resumo público é recalculado por slug.

Favorito

  • não passa por API;
  • fica apenas em localStorage.

API pública versionada

Além das rotas usadas pela UI do storefront, o domínio já pode ser lido por integrações em:

  • GET /api/v1/content/blog/posts
  • GET /api/v1/content/blog/posts/[slug]

Segurança operacional

As interações públicas usam controles leves mas importantes:

  • fingerprint de requisição;
  • hash do fingerprint;
  • rate limit por comentário e reação;
  • moderação administrativa para o que for conteúdo textual.

Estado atual da migração para banco

O blog já entrou na primeira camada de banco:

  • posts;
  • comentários;
  • reações.

Hoje o módulo trabalha em modo híbrido:

  • PostgreSQL como fonte preferencial quando disponível;
  • JSON local e runtime publicado como fallback e suporte operacional.

Isso nos permite migrar por domínio sem quebrar o painel nem o storefront.

Leitura seguinte