Painel de administração

O painel de administração EmDash é uma aplicação de página única (SPA) em React incorporada ao seu site Astro. Oferece uma interface completa de gestão de conteúdo para editoras e administradoras.

Visão geral da arquitetura

┌────────────────────────────────────────────────────────────────┐
│                    Shell Astro                                 │
│  /_emdash/admin/[...path].astro                              │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    SPA React                             │  │
│  │                                                          │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │  │
│  │  │  TanStack   │  │  TanStack   │  │     Kumo        │   │  │
│  │  │   Router    │  │   Query     │  │  Componentes    │   │  │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │  │
│  │                                                          │  │
│  │  ┌────────────────────────────────────────────────────┐  │  │
│  │  │           Cliente API REST                         │  │  │
│  │  │           /_emdash/api/*                         │  │  │
│  │  └────────────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

O admin é uma «grande ilha» React. O Astro gere o shell e a autenticação; toda a navegação e renderização dentro do admin são no cliente.

Pilha tecnológica

Estrutura de rotas

O admin monta-se em /_emdash/admin/ e usa encaminhamento no cliente:

UI baseada em manifesto

O admin não codifica manualmente coleções nem plugins. Obtém um manifesto do servidor:

GET /_emdash/api/manifest

Resposta:

{
	"collections": [
		{
			"slug": "posts",
			"label": "Blog Posts",
			"labelSingular": "Post",
			"icon": "file-text",
			"supports": ["drafts", "revisions", "preview"],
			"fields": [
				{ "slug": "title", "type": "string", "required": true },
				{ "slug": "content", "type": "portableText" }
			]
		}
	],
	"plugins": [
		{
			"id": "audit-log",
			"label": "Audit Log",
			"adminPages": [{ "path": "history", "label": "Audit History" }],
			"widgets": [{ "id": "recent-activity", "title": "Recent Activity" }]
		}
	],
	"taxonomies": [{ "name": "category", "label": "Categories", "hierarchical": true }],
	"version": "abc123"
}

O admin constrói navegação, formulários e editores apenas a partir deste manifesto. Vantagens:

• Alterações de esquema aparecem na hora — Não é preciso reconstruir o admin
• A UI de plugins integra-se automaticamente — Páginas e widgets a partir do manifesto
• Tipos na fronteira — Esquemas Zod permanecem no servidor

Fluxo de dados

Endpoints REST

O admin comunica exclusivamente via APIs REST:

API de conteúdo

API de esquema

API de mídia

Outras APIs

Paginação

Todos os endpoints de lista usam paginação por cursor:

{
  "items": [...],
  "nextCursor": "eyJpZCI6IjAxSjEyMzQ1NiJ9"
}

Obter a página seguinte:

GET /api/content/posts?cursor=eyJpZCI6IjAxSjEyMzQ1NiJ9

UI de admin de plugins

Os plugins podem estender o admin com páginas e widgets do painel. A integração gera um módulo virtual com imports estáticos:

// virtual:emdash/plugin-admins (gerado)
import * as pluginAdmin0 from "@emdash-cms/plugin-seo/admin";
import * as pluginAdmin1 from "@emdash-cms/plugin-analytics/admin";

export const pluginAdmins = {
	seo: pluginAdmin0,
	analytics: pluginAdmin1,
};

Páginas de plugin

As páginas de plugin montam-se sob /_emdash/admin/plugins/:pluginId/*:

// @emdash-cms/plugin-seo/src/admin.tsx
export const pages = [
	{
		path: "settings",
		component: SEOSettingsPage,
		label: "SEO Settings",
	},
];

Renderiza em: /_emdash/admin/plugins/seo/settings

Widgets do painel

Os plugins podem adicionar widgets ao painel:

export const widgets = [
	{
		id: "seo-overview",
		component: SEOWidget,
		title: "SEO Overview",
		size: "half", // "full" | "half" | "third"
	},
];

Autenticação

A rota shell do admin exige autenticação via middleware Astro:

// Lógica simplificada do middleware
export async function onRequest({ request, locals }, next) {
	const session = await getSession(request);

	if (request.url.includes("/_emdash/admin")) {
		if (!session?.user) {
			return redirect("/_emdash/admin/login");
		}
		locals.user = session.user;
	}

	return next();
}

A SPA do admin não trata do login: isso é uma página Astro que define o cookie de sessão.

Acesso por funções

Cada função vê partes diferentes do admin:

O endpoint do manifesto filtra coleções e recursos conforme a função da utilizadora.

Editor de conteúdo

O editor de conteúdo gera formulários dinamicamente a partir das definições de campo:

// Renderização simplificada do editor
function ContentEditor({ collection, fields }) {
	return (
		<form>
			{fields.map((field) => (
				<FieldWidget
					key={field.slug}
					type={field.type}
					label={field.label}
					required={field.required}
					options={field.options}
				/>
			))}
		</form>
	);
}

Cada tipo de campo tem um widget correspondente:

Editor de texto rico

Os campos Portable Text usam TipTap (ProseMirror):

A utilizadora escreve → TipTap (JSON ProseMirror) → Guardar → Portable Text (BD)
Carregar → Portable Text (BD) → TipTap (JSON ProseMirror) → Mostrar

A conversão ocorre nos limites de carregar/guardar com portableTextToProsemirror() e prosemirrorToPortableText().

Blocos suportados:

• Parágrafos, títulos (H1–H6)
• Listas com marcadores e numeradas
• Citações, blocos de código
• Imagens (da biblioteca de mídia)
• Ligações

Blocos desconhecidos de plugins ou importações mantêm-se como marcadores só de leitura.

Biblioteca de mídia

A biblioteca de mídia oferece:

• Vista em grelha e lista
• Pesquisa e filtro por tipo e data
• Upload por arrastar e largar
• Pré-visualização de imagem com metadados
• Seleção e eliminação em lote

Os uploads usam URLs assinadas para upload direto cliente → armazenamento:

Isto contorna limites de tamanho do corpo nos Workers e mostra progresso real de upload.

Próximos passos