> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Tarefas agendadas

Trabalho recorrente de workspace através das schedule actions.

## Passo a passo para iniciantes

Pré-requisitos: Leia os dois guias para iniciantes abaixo, conclua a configuração local da Web e abra este monorepo na raiz do seu editor. As configurações da Web pertencem a `apps/web/.env.local`; Next.js não lê a raiz `.env`. `/dashboard` no modo falso padrão é uma demonstração sem banco de dados; `/auth` precisa de um banco de dados migrado.

Termos rápidos: um espaço de trabalho consiste em usuários, dados e configurações separados de uma equipe. O servidor é o back-end confiável; mantenha as chaves do provedor fora do navegador e do código do telefone. Uma migração é uma alteração de versão do banco de dados que cria ou atualiza tabelas. Um modelo de IA é o mecanismo que responde; o catálogo de modelos é a lista do servidor de IDs e preços de modelos disponíveis. Um provedor é um serviço externo, como IA, e-mail ou serviço de cobrança. Um direito é uma concessão que permite que um espaço de trabalho use um recurso. Um webhook é uma mensagem que um serviço envia para o URL de outro serviço.

1. Abra Settings → Developers e use os controles Schedules para criar uma tarefa de teste com um tempo de execução UTC.

2. Mantenha o aplicativo em execução e disponibilize o mesmo `SCHEDULER_TICK_SECRET` somente servidor para o aplicativo e terminal; execute o comando abaixo na raiz do repositório.

3. Confirme o avanço do prazo e o trabalho atinge seu próprio status. Se nada for executado, verifique o horário UTC, o provedor do planejador e os logs do servidor; nunca cole o segredo no chat.

Para código personalizado, comece com o `prompts/README.md` fornecido e copie o prompt mais próximo: `prompts/new-app-screen.md` para uma tela de aplicativo ou `prompts/new-landing-page.md` para uma página pública. Para trabalho de servidor, banco de dados ou provedor, dê ao seu agente de codificação a tarefa deste guia e peça-lhe para ler `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` e espelhos `.ai/` correspondentes; inspecione os arquivos de origem exatos nomeados aqui; listar arquivos e verificações antes de editar; preservar a propriedade do espaço de trabalho e os segredos apenas do servidor; e mostrar a diferença. Informe o comportamento desejado, campos de entrada e saída, funções permitidas, sucessos e erros esperados e a conta de teste, provedor ou dispositivo. Use valores de amostra; nunca cole um segredo real.

[Antes de começar](https://supastack.dev/pt/docs/web/before-you-start.md)

[Noções básicas sobre terminais](https://supastack.dev/pt/docs/web/terminal-basics.md)

[Configuração local da Web](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md)

[Avisos do agente e memória do projeto](https://supastack.dev/pt/docs/web/agents.md)

```
corepack pnpm jobs:tick
```


## Armazene trabalhos recorrentes no banco de dados

O agendamento de configurações armazena o tipo de trabalho e a regra cron em linhas `job_schedule` com escopo no espaço de trabalho. Os campos Cron são avaliados em UTC. `createDrizzleJobScheduler.claimDueSchedules` reivindica linhas vencidas usando `FOR UPDATE SKIP LOCKED`, avança sua próxima execução e, em seguida, despacha manipuladores.

O `JobRunner` genérico promete enfileiramento/status/cancelamento. A recorrência pertence às linhas do agendador; A semântica do fluxo de trabalho do Trigger.dev permanece explícita.


## Gerar tiques do agendador

Defina um `SCHEDULER_TICK_SECRET` somente de servidor para ativar `POST /api/internal/scheduler-tick`. `corepack pnpm jobs:tick` chama isso de dev/CI; a configuração ausente retorna 404. Em `JOB_PROVIDER=trigger`, o cron `scheduler.tick` implementado aciona o agendador.

```
# Against a running local app, with SCHEDULER_TICK_SECRET configured:
corepack pnpm jobs:tick
```


## Verifique as reivindicações e a execução separadamente

Teste ticks sobrepostos, regras vencidas/não vencidas, linhas desativadas, falha do manipulador, cancelamento e agendamento de outro espaço de trabalho. Inspecione a reclamação/adiantamento e a conclusão do trabalho separadamente; uma linha reivindicada não é prova de trabalho concluído.

[Exemplo de email.digest enviado](https://supastack.dev/pt/docs/web/project-structure.md)

[Execução do trigger.dev](https://supastack.dev/pt/docs/modules/jobs.md)


## Instalação e configuração

O trabalho agendado — digests, limpezas, renovações — passa por schedule-actions em vez de timers ad hoc: listWorkspaceSchedules, upsertScheduleAction e removeScheduleAction gerem as tarefas cron de um workspace.

Um schedule nomeia a tarefa, a expressão cron e o workspace sob o qual corre. O worker resolve o contexto no momento da execução, por isso um schedule pausado ou eliminado deixa de produzir trabalho sem redeploy.

```
listWorkspaceSchedules()
upsertScheduleAction({ task, cron })
removeScheduleAction(formData)
```


## Fluxo de implementação

Trata cada execução agendada como input não confiável: volta a resolver o workspace e o entitlement dentro da run, porque o estado pode ter mudado desde o registo. Torna a tarefa idempotente — uma run repetida ou disparada duas vezes não pode duplicar efeitos.

Schedules são superfície operacional: mantém-nos visíveis em settings ou logs para que um schedule preso ou descontrolado seja encontrado antes de os utilizadores notarem.


## Verificação e resolução de problemas

Dispara o schedule manualmente numa sandbox, pausa-o, verifica que um workspace desativado deixa de produzir runs e confirma que um disparo duplicado produz um efeito. Mantém expressões cron em configuração gerida, não espalhadas pelo código das tarefas.


## Seguinte

[Email transacional](https://supastack.dev/pt/docs/modules/email.md)