OPERAÇÃO / MULTI-GUILD

Multi-guild

Mantenha configuração, recursos, filas e interações independentes quando o mesmo bot atende vários servidores.

Context isolationGuild resourcesScoped runtime

O problema que o escopo resolve#

Sem isolamento, duas guilds podem disputar a mesma configuração, fila ou instância de componente.

Configuração

Cada guild possui canais, cargos e variáveis próprios.

Concorrência

Filas lógicas recebem a guild na chave interna quando há contexto.

Interações

Prompts e paginações validam autor, guild e Client responsável.

Contexto automático#

1async function sendSupportPanel() {2  const config = Client.appConfig()3  const channel = Client.getAppChannels().support4  const staff = Client.getAppRoles().staff56  if (!channel) return78  await sendPanel(channel.Id, {9    title: config.variables?.tickets?.title ?? 'Suporte',10    staffRoleId: staff?.Id11  })12}1314Client.on(Events.GuildMemberAdd, {15  execute: async member => {16    // O evento ativa o contexto de member.guild.id.17    await sendSupportPanel()18  }19})

A função sendSupportPanel não recebe guildId, porque foi chamada durante um evento contextualizado. Se a mesma função também rodar em um script administrativo sem contexto, passe o ID explicitamente em sua assinatura.

Contexto explícito#

Jobs externos, scripts e callbacks fora do runtime precisam indicar a guild que desejam ler.

1async function synchronizeAllGuilds() {2  for (const guild of Client.guilds.cache.values()) {3    const config = Client.appConfig(guild.id)4    const channels = Client.getAppChannels(guild.id)5    const roles = Client.getAppRoles(guild.id)67    await syncGuild({8      guildId: guild.id,9      auditChannelId: channels.audit?.Id,10      staffRoleId: roles.staff?.Id,11      options: config.variables?.sync ?? {}12    })13  }14}

Filas e cooldowns#

O Core acrescenta o escopo quando a chamada ocorre dentro de uma execução contextualizada.

1Client.slash({2  data: new SlashCommandBuilder()3    .setName('sync')4    .setDescription('Sincroniza o painel.'),5  cooldown: '15s',6  execute: async interaction => {7    await interaction.deferReply({ flags: 64 })89    await Client.queue('panel-sync', async () => {10      await syncPanel(interaction.guildId)11    })1213    await interaction.editReply('Painel sincronizado.')14  }15})

Duas execuções de panel-sync na mesma guild entram na mesma fila. A mesma chave em outra guild segue independentemente. O cooldown de comando também considera a guild para não bloquear o usuário em todos os servidores.

Prompts e paginações escopados#

Cada solicitação registra uma instância temporária vinculada ao autor e à guild.

1Client.registerPaginator('members-pages', async context => {2  const members = context.guildId3    ? await memberRepository.list(context.guildId)4    : []56  return Paginator.dynamic({7    id: 'members-pages',8    ownerId: context.ownerId,9    guildId: context.guildId,10    data: members,11    pageSize: 10,12    render: renderMembersPage13  })14})

Outro usuário não consegue navegar pela instância aberta pelo autor.
Um componente enviado em uma guild não é resolvido pela instância de outra guild.
Dois Clients no mesmo processo usam namespaces de runtime separados.
Dados retornados por uma factory devem ser consultados usando context.guildId.

Checklist multi-guild#

Toda tabela ou coleção persistente inclui guildId quando os dados pertencem ao servidor.
Caches criados pela aplicação usam Map<guildId, value> ou uma chave composta.
IDs de canais e cargos vêm de aliases resolvidos, não de constantes globais.
Factories de prompts e paginações usam context.guildId.
Tasks de escopo guild não gravam o resultado em uma variável global única.
Logs de operação incluem a guild quando isso ajuda a diagnosticar a origem.