Começar em 10 minutos

Esta página são os seus primeiros dez minutos dentro do Archestack: iniciar sessão num trial novo, perceber cada painel da aplicação, fazer a sua primeira alteração e aprender os atalhos de teclado que transformam a UI de "razoável" em "rápida". No fim saberá o suficiente para seguir qualquer um dos outros guias sem se perder.

Ainda não tem um trial? Abra archestack.eu e clique em Try it live - 7-day trial. Inicie sessão com a Google. O seu ambiente privado estará pronto em cerca de 30 segundos e será encaminhado automaticamente para o respetivo painel. Guarde o URL nos favoritos, é único para o seu trial.

1. Iniciar sessão no seu trial

Cada trial recebe um URL único no formato https://<slug>.trial.archestack.eu. O banner do trial no topo de cada ecrã mostra quantos dias faltam antes de o ambiente ser destruído. A gravidade aumenta à medida que se aproxima do prazo (info, aviso, erro) para que saiba de relance se tem semanas ou horas.

A aplicação abre no Home dashboard, que está intencionalmente vazio até que construa algo. Não se preocupe, é mesmo essa a ideia. Na primeira vez, os únicos sinais de que "está dentro" são a barra lateral à esquerda e o seu nome no canto superior direito.

O que é diferente no modo trial

Algumas funcionalidades estão desativadas no ambiente de trial para manter a infraestrutura partilhada segura. Aparecem a cinzento (ou devolvem 403 se as tentar chamar diretamente):

• Database Backups - desativado para evitar abuso de disco.
• Renderização de PDF - tanto o painel de pré-visualização do editor como o endpoint público de geração devolvem 403; o editor de templates em si continua a funcionar para autoria (data script, HTML, definições), mas não verá um PDF renderizado dentro de um trial.

Tudo o resto funciona normalmente. Quando estiver pronto para usar as funcionalidades bloqueadas, contacte a equipa através do botão Upgrade no banner do trial.

2. O layout, num só parágrafo

À esquerda, a barra lateral começa com um botão Quick Search (ou prima Ctrl/Cmd+K) que abre a paleta de comandos, mais uma entrada Home, e depois abre numa secção ADMINISTRATION dividida em EDITOR (onde passará a maior parte do tempo: Business Entities, Page Editor, Business Events, Script Modules, etc.) e SYSTEM (ferramentas de administração: Database Deployments, Schema Designer, User Management, Branding, Backups). O ícone de sino (topo esquerdo, junto ao logótipo do Archestack) mostra falhas não lidas do Event Log. No fundo da barra lateral está o alternador de tema (sol/lua), o menu do seu perfil, um alternador de Desktop mode e um botão para colapsar a barra lateral. Assim que publicar uma página, ela aparece sob a sua própria secção Modules acima de ADMINISTRATION.

Uma visita guiada mais detalhada

• Barra lateral - grupo EDITOR. Business Entities, Object Browser, Third Party, Business Events, Script Modules, Frontend Templates, PDF Templates, Page Editor, Scheduled Events, Event Logs, Packages, Build with AI. O assistente Build with AI compõe um prompt para um LLM externo (Claude, ChatGPT, Gemini) e aplica o plano JSON que recebe de volta; ver "AI Builder" na página de referência.
• Barra lateral - grupo SYSTEM. Database Deployments, Schema Designer, User Management, Translations, Business Units, Database Backups, Branding. Menos frequente, mas essencial quando precisar.
• Modules (acima de ADMINISTRATION). Vazio até publicar a sua primeira página. As páginas publicadas vivem aqui agrupadas por categoria, e é assim que os utilizadores finais navegam até elas.
• Cartões de estatísticas do dashboard. Tables / Business Entities / Pages / Event Triggers / Scripts / Scheduled; cada bloco é clicável e leva-o à página de administração relevante.
• Painel Quick Actions (lado direito do dashboard). Atalhos de um clique: New Page, New Entity, New Trigger, New Script, Build with AI, Schema Designer.
• Separadores no topo. A maioria das ferramentas de edição abrem como separadores no painel principal; pode ter vários abertos ao mesmo tempo. Clique num separador para alternar; feche com ×. Clique em + para abrir um novo separador. O estado dos separadores é guardado no URL, por isso recarregar mantém os seus separadores.
• Ícone do sino (topo esquerdo, junto ao logótipo). Notificações de falhas de Business Events, Script Modules e Scheduled Events. Em tempo real via SignalR, não precisa de recarregar.
• Controlos no fundo da barra lateral. Alternador de tema (sol/lua; o admin tem tema escuro por defeito, este site Learn tem claro por defeito, alternam de forma independente), avatar do perfil (idioma + terminar sessão), alternador de Desktop mode e colapsar barra lateral.

Desktop mode

Em ecrãs largos pode premir Ctrl/Cmd+Shift+D para mudar para Desktop mode, uma UI em janelas onde cada ferramenta abre como uma janela arrastável com uma dock em baixo. É a mesma aplicação, apenas com um layout diferente. Use o que lhe parecer mais natural; a documentação refere o layout em barra lateral porque é o predefinido.

3. Faça a sua primeira alteração em 5 minutos

Prefere uma visita guiada? O dashboard tem um botão Start guided setup no canto superior direito. Abre um painel que o conduz pelos seis blocos centrais (tables → entities → pages → events → scripts → PDFs), destaca o próximo passo a dar, e pode pré-carregar um mini-CRM (tabelas Customer / Contact / Note) para ter algo com que brincar. O passo a passo abaixo cobre o mesmo terreno manualmente, escolha o que lhe parecer melhor.

A forma mais rápida de se sentir produtivo é desenhar uma tabela simples, fazer deploy e ver os dados. Vamos criar uma tabela "note".

Desenhar a tabela

1. Abra Schema Designer a partir da secção de administração da barra lateral (rota: /schema-designer).
2. Na barra de ferramentas no topo, clique no botão de ícone Add Table.
3. Abre-se um diálogo com o título Create New Table. O campo "Table name" sugere a convenção: minúsculas com underscores. Escreva note. Clique em Create.
4. A nova tabela aparece no canvas e o painel à direita abre com três separadores: Columns, Indexes, Relations.
5. Está no separador Columns. O sistema já adicionou uma coluna id (chave primária SERIAL, bloqueada). No final da lista de colunas há uma caixa com contorno tracejado "Add column". Adicione mais três colunas, uma de cada vez:
   • title · tipo VARCHAR, comprimento 500, NULL desligado (obrigatório).
   • body · tipo TEXT, NULL ligado (opcional).
   • created_at · tipo TIMESTAMPTZ, default now().
   Para cada uma: escreva o nome no campo de nome da coluna, escolha o tipo no menu pendente Type, clique em Add Column. Depois clique na nova coluna para a expandir e ajustar os toggles (PK / NULL / UQ) e os campos Length / Default conforme necessário.
6. O schema guarda automaticamente; veja o indicador no canto inferior esquerdo passar de "Auto saving…" para "Saved".

O Archestack adiciona quatro colunas de auditoria, created_at, updated_at, created_by, updated_by, a cada tabela automaticamente e carimba-as em cada insert e update. O created_at acima é, portanto, opcional (adicionamo-lo para corresponder à captura); nunca tem de criar ou manter essas quatro à mão.

Fazer deploy

1. Na barra de ferramentas do Schema Designer, clique no botão Deploy (ícone de foguetão, verde). É levado para /database-deployments/configure/new.
2. Cai no separador Configuration. Os painéis de scripts pre- e post-deployment estão vazios (predefinição). Mude para o separador Generated SQL para ver a migração que a plataforma produziu, deve ser um CREATE TABLE "note" (…).
3. Se o SQL parecer correto, clique no botão Deploy no canto superior direito. O estado atualiza em tempo real; em caso de sucesso, a linha do deployment em Database Deployments → Overview mostra "Succeeded".

Adicionar alguns dados

Para ver a sua nova tabela, abra Object Browser, escolha note na lista de tabelas e clique em Add row. Escreva um título e um corpo, guarde. Acabou de criar a sua primeira informação.

Se algo não parecer bem

• A tabela não aparece no Object Browser? Verifique Database Deployments; se o deployment não foi bem-sucedido, a tabela não existe. A maioria das falhas são conflitos de nome ou combinações de tipo/comprimento inválidas. A coluna de estado da linha do deployment diz-lhe qual é.
• Não consegue ver o separador Columns no Schema Designer? Provavelmente não selecionou uma tabela; clique num nó de tabela no canvas. O painel à direita só aparece quando algo está selecionado.
• O botão Deploy na barra de ferramentas do Schema Designer está a cinzento? Normalmente significa que não há alterações pendentes. Verifique o indicador de auto-save; se mostrar "Saved" e não tiver feito alterações desde o último deployment, não há nada para fazer deploy.

4. Envolva-a numa página real

O Object Browser é uma vista para utilizadores avançados; os utilizadores finais querem uma interface mais amigável. Vamos dar-lhes uma:

1. Abra Business Entities e clique em Create. Abre-se um editor em página inteira. Defina Entity Name como note, escolha Master Table = note, escolha Label Column = title. Guarde. O separador Visual mostra as colunas geradas automaticamente, pode deixá-las como estão.
2. Abra Page Editor (rota: /pages) e clique em Create. Preencha Page Name = Notes, Page Route = /notes, Business Entity = note. O construtor de páginas gera automaticamente um layout sensato com base nas colunas da BE.
3. Vire o Switch Published no cabeçalho do topo para ON. A página aparece em Published Pages na barra lateral. Clique nela, tem uma aplicação funcional de introdução de dados com pesquisa, filtros e edição.

É este o ciclo completo: Schema → Deploy → Business Entity → Page → Publish. Cada funcionalidade no Archestack ou se constrói sobre este ciclo ou estende-o (eventos disparam quando os dados mudam, scripts correm num horário, packages agrupam o resultado do ciclo para promoção).

5. Atalhos de teclado que o tornam rápido

A UI do Archestack é amigável para o rato, mas a maioria dos utilizadores experientes vive no teclado. A lista abaixo cobre os atalhos que compensam de imediato.

Globais

• Ctrl/Cmd + K - abre a Command palette. Pesquise qualquer página, ação ou Business Entity pelo nome. A forma mais rápida de navegar.
• Ctrl/Cmd + Shift + D - alterna Desktop mode (UI em janelas ↔ UI em barra lateral).
• Esc - fecha o diálogo / popover do topo.

Em qualquer grelha de lista

• ↑ / ↓ - move a seleção de linha.
• Enter - abre a linha selecionada.
• Ctrl/Cmd + F - foca a caixa de pesquisa.

Em editores de código (scripts, data scripts de PDF, frontend templates)

• Ctrl/Cmd + Space - mostra sugestões de IntelliSense. Note que Db, Modules, Entity, OldEntity e Log são os únicos globais; o autocompletar sobre estes funciona dentro de qualquer script.
• Tab - aceita a sugestão destacada. (Accept-on-commit-character está intencionalmente desativado para evitar inserções acidentais quando pretende escrever uma vírgula ou um parêntese.)
• Ctrl/Cmd + S - guarda.

6. A Command Palette merece a sua própria secção

Ctrl/Cmd + K abre um overlay de pesquisa fuzzy que permite saltar para qualquer parte da aplicação escrevendo dois ou três caracteres. Pesquisa:

• Pages (tanto ferramentas de administração como as suas páginas publicadas).
• Business Entities pelo nome.
• Ações como "create new BE", "open Branding", "deploy schema".
• Itens recentes que abriu, reencontra-os com uma tecla.

A paleta abre com o foco na caixa de pesquisa, por isso pode começar a escrever de imediato. As setas para cima/baixo navegam, Enter seleciona, Esc fecha. Ao fim de algumas horas de uso vai dar por si a usá-la para navegar mais do que a barra lateral.

7. Para onde ir a seguir

• Conceitos centrais - leia isto se quiser um modelo mental antes de clicar em mais alguma coisa. Cobre Business Entities, Pages, Events, Scripts e a API Db invocável a partir de scripts.
• Construa a sua primeira aplicação - um percurso mais longo e opinativo que termina com um mini-CRM multi-página (companies / contacts / deals), ligado com eventos de auto-stamping e um script de recálculo.
• Gerar faturas em PDF - parte dos dados do first-app para adicionar um template de fatura imprimível.
• Referência - entradas focadas por ferramenta, nas quais pode mergulhar quando tiver uma dúvida específica.

Perguntas comuns no início

"Posso anular um deployment?"

Não diretamente, não há um botão Undo. A recuperação limpa passa ou por aplicar um deployment corretivo (largar uma coluna que acabou de adicionar, etc.) ou por restaurar a partir de um backup. Num ambiente pago, faça um backup antes de alterações arriscadas. Num trial, a recuperação mais simples é começar um trial novo.

"Posso ter várias páginas sobre a mesma BE?"

Sim, quantas quiser. Rotas diferentes, disposições diferentes, escolhas diferentes de colunas. Padrão comum: uma página de lista simples em /customers para todos e uma /customers/admin mais detalhada para utilizadores de back-office (controlada por uma Business Unit ou role).

"Onde edito as etiquetas dos campos e os cabeçalhos das colunas?"

Em dois sítios, consoante o que quer mudar. A etiqueta que aparece na página (por exemplo "Company name" em vez de "Name") vem da configuração da coluna na Business Entity. A etiqueta que aparece a nível de sistema para uma chave de tradução (por exemplo strings de UI como "Save", "Cancel") vive em Translations.

"A minha página está vazia. Onde estão os meus dados?"

Três suspeitos habituais, por ordem de probabilidade:

• A Business Unit ativa está errada, verifique o seletor de BU na barra superior.
• A Business Entity tem um filtro predefinido que está a esconder os seus dados, abra a BE e verifique.
• Adicionou linhas no Object Browser a uma tabela diferente daquela que pensa (veja o nome da tabela no breadcrumb).

"Como obtenho o email do utilizador atual num script ou trigger?"

Não consegue, por agora. Os scripts só têm Entity, OldEntity, Log, Db e Modules; não existe um global User. As expressões de template ({{ … }}) também não têm um token {{ user.email }}. Se precisar da identidade do utilizador numa regra, capture-a a partir do front-end e passe-a no registo no momento da inserção, e depois leia-a a partir daí.

"Posso correr o Archestack localmente na minha máquina?"

Sim, existe um docker-compose.yml no repositório que sobe um stack auto-contido com PostgreSQL + Keycloak + API + Web. Está documentado para engenheiros que querem desenvolver a própria plataforma. Para avaliação, o ambiente de trial é muito mais rápido para começar.

"Como estendo a plataforma com código personalizado?"

Dois pontos de extensão cobrem quase tudo: Script Modules para lógica de backend (C# compilado em runtime) e Frontend Templates para fragmentos de UI personalizados (TSX). Para alterações mais profundas, controladores personalizados ou novas tabelas de que a própria plataforma precisa, isso é território de fork-and-build e está fora do âmbito deste site.