---
title: Bloqueios de Recursos
slug: studio/bloqueios-de-recursos
docTags:
createdAt: 2026-04-28T18:37:54.693Z
---
# 1 - Visão geral
O sistema Resource Lock oferece proteção colaborativa de edição ao impedir que múltiplos usuários editem simultaneamente a mesma tela ou composição. Isso garante a integridade dos dados e previne conflitos em ambientes multiusuário.
**Principais Recursos**
- **Gerenciamento Automático de Bloqueios**\: Recursos são automaticamente bloqueados quando abertos para edição
- **Indicadores Visuais**\: Feedback claro da interface mostrando quem está editando o quê
- **Proteção contra Tempo Morto**\: Bloqueios expiram automaticamente após 5 minutos de inatividade
- **Mecanismo de Batimentos Cardíacos**\: Sessões de edição ativa renovam automaticamente os bloqueios
- **Liberação forçada**\: Administradores podem liberar bloqueios à força quando necessário
- **Atualizações em tempo real**\: Atualizações de status do bloqueio via mecanismo de polling
- **Desabilitação Abrangente**\: Todas as superfícies de edição são desativadas quando bloqueadas por outro usuário
**Recursos**
- **Screens**\: Screens individuais de aplicação
- **Composições**\: Composições componentes reutilizáveis
***
# 2 - Como Funciona
**Ciclo de Vida da Trava**
**Fluxo de Aquisição de Locks**
1. **Usuário Abre Recurso**\: O usuário navega até uma tela ou composição
2. **Solicitação de Bloqueio**\: A interface envia a solicitaçãoPOST /api/locks/acquire
3. **Verificação de Bloqueio**\: O backend verifica se o recurso já está bloqueado
4. **Conceda ou negue**\:
- Se desbloqueado: O bloqueio é concedido e armazenado no banco de dados
- Se bloqueado pelo mesmo usuário: O bloqueio é concedido (reentrada permitida)
- Se bloqueado por outro usuário: Solicitação negada com detalhes do bloqueio
5. **Batimentos cardíacos iniciados**\: O frontend começa a enviar batimentos cardíacos a cada 4 segundos
6. **Atualizações da interface**\: O estado travado é refletido em todos os componentes da interface
**Mecanismo do Batimento Cardíaco**
O mecanismo do batimento cardíaco mantém as travas ativas durante a edição ativa:
- **Intervalo**\: A cada 4 segundos
- **Ponto final**\: `POST /api/locks/renew`
- **Propósito**\: Estende o tempo de expiração do bloqueio
- **Automático**\: Executa em segundo plano enquanto o recurso está aberto
- **Limpeza**\: Para quando o usuário navega para fora ou fecha o recurso
**Expiração da Fechadura**
Fechaduras expiram automaticamente após 5 minutos sem batimentos cardíacos:
- **Tempo\:** 300 segundos (5 minutos)
- **Propósito**\: Evitar que travas obsoletas bloqueiem recursos
- **Limpeza Automática**\: O backend remove automaticamente fechaduras vencidas
- **Período de Carência**\: Garante que bloqueios não persistam caso o usuário feche o navegador inesperadamente
***
# 3 - Implementação Backend
**Esquema de Banco de Dados**
```javascript
CREATE TABLE lowcode_studio.resource_locks (
id TEXT PRIMARY KEY,
resource_type TEXT NOT NULL, -- 'screen' or 'composition'
resource_id TEXT NOT NULL,
locked_by TEXT NOT NULL, -- User ID
locked_at BIGINT NOT NULL, -- Unix timestamp in milliseconds
expires_at BIGINT NOT NULL, -- Unix timestamp in milliseconds
UNIQUE(resource_type, resource_id)
);
CREATE INDEX idx_resource_locks_resource
ON lowcode_studio.resource_locks(resource_type, resource_id);
CREATE INDEX idx_resource_locks_expires
ON lowcode_studio.resource_locks(expires_at);
```
**API Endpoints**
Adquirir Lock
```javascript
POST /api/locks/acquire
Content-Type: application/json
{
"resourceType": "screen",
"resourceId": "uuid-here",
"userId": "user-id-here"
}
```
**Resposta (Sucesso - 200)\:**
```javascript
{
"success": true,
"lock": {
"id": "lock-id",
"resourceType": "screen",
"resourceId": "uuid-here",
"lockedBy": "user-id-here",
"lockedByUser": {
"id": "user-id-here",
"firstName": "John",
"lastName": "Doe"
},
"lockedAt": 1737648000000,
"expiresAt": 1737648300000
}
}
```
**Resposta (Já Bloqueada - 409)\:**
```javascript
{
"success": false,
"error": "Resource is locked by another user",
"lock": {
"id": "lock-id",
"resourceType": "screen",
"resourceId": "uuid-here",
"lockedBy": "other-user-id",
"lockedByUser": {
"id": "other-user-id",
"firstName": "Jane",
"lastName": "Smith"
},
"lockedAt": 1737647900000,
"expiresAt": 1737648200000
}
}
```
**Renovar Trava**
```javascript
POST /api/locks/renew
Content-Type: application/json
{
"resourceType": "screen",
"resourceId": "uuid-here",
"userId": "user-id-here"
}
```
**Resposta (200)\:**
```javascript
{
"success": true,
"expiresAt": 1737648600000
}
```
**Trava de Liberação**
```javascript
POST /api/locks/release
Content-Type: application/json
{
"resourceType": "screen",
"resourceId": "uuid-here",
"userId": "user-id-here"
}
```
**Resposta (200)\:**
```javascript
{
"success": true
}
```
******Trava de Liberação Forçada** ****
```javascript
POST /api/locks/force
Content-Type: application/json
{
"resourceType": "screen",
"resourceId": "uuid-here"
}
```
**Resposta (200)\:**
```javascript
{
"success": true
}
```
**Conseguir Fechaduras por Recurso**
```javascript
GET /api/locks?resourceType=screen&resourceId=uuid-here
```
**Resposta (200)\:**
```javascript
{
"locks": [
{
"id": "lock-id",
"resourceType": "screen",
"resourceId": "uuid-here",
"lockedBy": "user-id",
"lockedByUser": {
"id": "user-id",
"firstName": "John",
"lastName": "Doe"
},
"lockedAt": 1737648000000,
"expiresAt": 1737648300000
}
]
}
```
***
# 4 - Implementação Frontend
### **Arquitetura de Loja**
O sistema de bloqueio utiliza sinais Preact para gerenciamento de estado reativo:
**Arquivo**\: `client/src/features/project/stores/resource-locks.ts`
```javascript
// Global signals
export const resourceLocks = signal>(new Map());
export const lockHeartbeats = signal>(new Map());
// Computed signal for editing state
export const isEditingDisabled = computed(() => {
const currentActive = editMode.value === "composition"
? activeComposition.value
: activeScreen.value;
if (!currentActive) return false;
const lockStatus = getResourceLockStatus(
editMode.value === "composition" ? "composition" : "screen",
currentActive.uuid,
userProfile.value?.id || ""
);
return lockStatus.isLocked && !lockStatus.isOwnedByCurrentUser;
});
```
### **Funções de Trava**
**adquireResourceLock **
Tentativas de obter um bloqueio em um recurso:
```javascript
const result = await acquireResourceLock('screen', screenUuid, userId);
if (result.success) {
// Lock acquired, start heartbeat
} else {
// Lock denied, show notification
}
```
**renewResourceLock **
Renova uma fechadura existente (chamada por batimentos cardíacos):
```javascript
await renewResourceLock('screen', screenUuid, userId);
```
**releaseResourceLock **
Libera um bloqueio quando o usuário termina de editar:
```javascript
await releaseResourceLock('screen', screenUuid, userId);
```
**getResourceLockStatus **
Verifica o status atual do bloqueio de um recurso:
```javascript
const status = getResourceLockStatus('screen', screenUuid, userId);
// Returns: { isLocked, isOwnedByCurrentUser, lock }
```
### **Componentes da interface**
**Notificações do Canvas**
**Arquivo**\: `client/src/features/project/details/components/layout/canvas-notifications.tsx`
Exibe notificações de bloqueio e composições órfãs no topo da tela:
- **Notificação de Bloqueio**\: Mostra quem está editando o recurso
- **Avatar do Usuário**\: Avatar codificado por cores com base no ID do usuário
- **Exibição de Horas**\: Mostra quando a fechadura foi adquirida
- **Ícone de Cadeado**\: Indicador visual no final do banner
**Lista de Tela**
**Arquivo**\: `client/src/features/project/details/components/left-panel/screen-list.tsx`
Mostra indicadores de bloqueio ao lado das telas bloqueadas:
- **Ícone de Cadeado**\: Ícone pequeno de cadeado ao lado do nome de usuário
- **Avatar do Usuário**\: Avatar minúsculo mostrando quem está com o bloqueio
- **Dica de ferramenta**\: Passe o mouse para ver o nome completo do usuário
**Árvore de Elementos**
**Arquivo**\: `client/src/features/project/details/components/left-panel/elements-tree/`
Desativa manipulação de elementos quando bloqueado:
- **Botão de Adicionar**\: Oculto quando bloqueado
- **Arrastar e Soltar**\: Desativado quando bloqueado
- **Menu de Contexto**\: Vazio quando bloqueado
- **Reordenamento**\: Impedido quando travado
****
**Painel Direito**
**Arquivo**: `client/src/features/project/details/components/right-panel/index.tsx`
Torna as abas legíveis, mas o conteúdo não editável:
- **Abas** \: Permanecam clicáveis para navegação
- **Conteúdo**\: Desativado com pointer-events-none opacity-60
- **Todos os Painéis**\: Propriedades, Estilos, Encadernações, Documentação, Configurações
****
**Ações de Tela**
**Arquivo**\: `client/src/features/project/details/components/renderer/index.tsx`
Ocultar botões de ação de elemento quando bloqueados:
- **Mover-se para cima/baixo**\: Oculto
- **Excluir**\: Oculto
- **Cópia**\: Oculta
- **Largura do Rótulo**\: Definido para 0 quando bloqueado
****
**Estratégia de Pesquisa**
O sistema utiliza polling adaptativo para verificar o status do bloqueio:
```javascript
// With active locks: Poll every 5 seconds
// Without locks: Poll every 30 seconds
const refetchInterval = hasActiveLocks ? 5000 : 30000;
useQuery({
queryKey: ['resource-locks', projectId],
queryFn: () => fetchResourceLocks(projectId),
refetchInterval,
staleTime: 0,
});
```
***
# 5 - Experiência do Usuário
### Ao abrir um recurso bloqueado
1. **Navegação**\: Usuário clica em uma tela/composição bloqueada
2. **Checagem de Bloqueio**\: Sistema verifica se o recurso está bloqueado
3. **Notificação**\: Banner aparece no topo da tela
4. **UI desativada**\: Todos os controles de edição estão desativados
5. **Modo Somente Leitura**\: O usuário pode visualizar, mas não editar
### **Indicadores Visuais**
**Faixa de Fechadura (Tela)**
:::BlockQuote
┌─────────────────────────────────────────────────────────┐
│ John Doe is editing this screen (2 minutes ago) │
└─────────────────────────────────────────────────────────┘
:::
Características: \* Fundo vermelho () \* Avatar do usuário com fundo codificado por cores \* Exibição do nome completo \* Tempo desde que a fechadura foi adquirida \* Ícone de cadeado no final `bg-red-50 border-red-200`
****
**Indicador de Lista de Tela**
:::BlockQuote
Home Screen \[JD]
Profile Screen
Settings Screen \[JS]
:::
Características: \* Ícone pequeno de cadeado ao lado do nome \* Avatar de usuário pequeno (8px) \* Dica de ferramenta ao passar o mouse mostrando o nome completo
****
**Quando outro usuário adquire o bloqueio**
1. **Detecção de Polling**\: Frontend detecta novo lock via polling
2. **Atualização da interface**\: Indicadores de trava aparecem imediatamente
3. **Edição desativada**\: Todos os controles se tornam não interativos
4. **Edições Atuais**\: As alterações locais do usuário permanecem, mas não podem ser salvas
5. **Notificação**\: Notificação opcional de toast (não implementada atualmente)
****
**Quando a Tranca é Liberada**
1. **Detecção de Liberação**\: O sondamento detecta remoção de trava
2. **Remoção de notificações**\: Banner de bloqueio desaparece
3. **UI Ativada**\: Todos os controles de edição ficam ativos
4. **Auto-Travamento**\: Se o usuário ainda estiver no recurso, ele pode adquirir o bloqueio
***
# 6 - Configuração
**Tempo de Espera do Bloqueio**
Altere o tempo de validade da fechadura:
**Backend** ():`server/src/routes/locks/handlers.ts`
```javascript
const LOCK_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
```
**Intervalo de Batimentos cardíacos**
Altere a frequência com que os cadeados são renovados:
**Frontend** ():`client/src/features/project/stores/resource-locks.ts`
```javascript
const HEARTBEAT_INTERVAL = 4000; // 4 seconds
```
**Intervalo de votação**
Alterem a frequência de pesquisa de status do bloqueio:
**Frontend** ():`client/src/features/project/queries/resource-locks.ts`
```javascript
const WITH_LOCKS_INTERVAL = 5000; // 5 seconds
const WITHOUT_LOCKS_INTERVAL = 30000; // 30 seconds
```
***
# 7 - Solução de problemas
**Trava não soltando**
**Sintomas**\: Usuário fechou o navegador, mas o bloqueio persiste
**Solução**\: Espere 5 minutos pela expiração automática ou use liberação forçada:
```javascript
curl -X POST http://localhost:8000/api/locks/force \
-H "Content-Type: application/json" \
-d '{
"resourceType": "screen",
"resourceId": "uuid-here"
}'
```
****
**Múltiplos usuários veem diferentes estados de bloqueio**
**Sintomas**\: Usuários veem informações conflitantes sobre bloqueios
**Causa**\: Intervalo de pesquisa muito longo ou problemas de rede
**Soluções**\:
1. Reduzir o intervalo de votação na produção.
2. Verifique a conectividade da rede.
3. Verificar se o backend está respondendo.
4. Verifique a conexão com o banco de dados.
****
**Bloqueio adquirido, mas interface não atualizando**
**Sintomas**\: O bloqueio existe no banco de dados, mas a interface mostra desbloqueada
**Causa**\: Problema com o cache de React Query ou sinal que não está sendo atualizado
**Soluções**\:
1. Verifique o console do navegador para erros.
2. Verificar é chamado em componentes.
3. Limpar o cache de Consultas React.
4. Atualizar a página `useSignals()`
**Batimentos cardíacos não enviando**
**Sintomas**\: O bloqueio expira enquanto o usuário está editando ativamente
**Causa**\: Intervalo de batimentos cardíacos parou ou problemas na rede
**Soluções**\:
1. Verifique o console do navegador para erros de rede.
2. Verificar se o usuário ainda está autenticado.
3. Verifique se o intervalo está sendo liberado incorretamente.
4. Verificar se o endpoint backend está funcionando `/api/locks/renew`
**As cores dos avatares são idênticas**
**Sintomas**\: Usuários diferentes têm a mesma cor de avatar
**Causa**\: Colisão de hash no algoritmo de geração de cor
**Solução**\: Isso foi corrigido com o hash rolante polinomial. Se ainda ocorrer:
1. Verificar se o código mais recente foi implantado
2. Função de verificação
3. Garantir que está sendo passado para o componente `generateAvatarColor()userIdUserAvatar`
***
# 8. Melhores Práticas
### **Para desenvolvedores**
1. **Sempre Limpe**\: Garanta que as travas sejam liberadas quando o componente for desmontado
2. **Erros de Manipulação**\: Gerencie com elegância falhas de aquisição de travas
3. **Use Sinal Calculado**\: Referência em vez de recalcularisEditingDisabled
4. **Teste de Concorrência**\: Teste com múltiplos usuários editando simultaneamente
5. **Monitore o desempenho\:** Fique atento a excesso de polling ou chamadas API
****
### **Para usuários**
1. **Fechar Trancas de Liberação**\: Feche recursos ao terminar a edição
2. **Não force o fechamento**\: Use a navegação adequada para garantir a limpeza
3. **Aguarde a expiração**\: Se a trava estiver presa, espere 5 minutos
4. **Comunique\:** Coordena com a equipe quem edita o quê
5. **Atualize se necessário**\: Se a interface parecer travada, atualize a página
### Para Administradores
1. **Fechaduras de monitor**\: Verifique periodicamente se estão desgastadas
2. **Definir Tempos Razoáveis**\: Equilíbrio entre usabilidade e disponibilidade de recursos
3. **Liberação Forçada com Parcimónia**\: Use apenas quando necessário
4. **Manutenção do Banco de Dados**\: Limpeza regular de registros de fechaduras vencidas
5. **Análise de Log**\: Monitorar padrões de aquisição de bloqueios para detectar problemas
***
# 9 - Melhorias Futuras
### Características Planejadas
- **Suporte a WebSocket**\: Notificações de bloqueio em tempo real em vez de sondagem
- **Roubo de Fechaduras**\: Permitir que administradores forcem a aquisição de travas
- **Histórico de Bloqueios**\: Rastreie quem travou recursos e quando
- **Análise de Fechaduras**\: Monitore os padrões de uso das fechaduras
- **Cursores Colaborativos**\: Mostre onde outros usuários estão trabalhando
- **Resolução de Conflitos**\: Mesclar mudanças conflitantes quando múltiplos usuários editam
- **Solicitações de Trava**\: Solicita liberação do bloqueio do atual detentor
- **Fila de Bloqueio**\: Usuários em fila aguardando um recurso travado
### Otimizações de desempenho
- **Redis Cache**\: Armazene bloqueios no Redis para acesso mais rápido
- **Assinaturas GraphQL**\: Atualizações em tempo real via assinaturas
- **Bloqueio Otimista**\: Permitir edição com detecção de conflitos
- **Pool de Bloqueios**\: Agrupar múltiplos recursos sob um único bloqueio
- **Pesquisa Inteligente**\: Ajuste a frequência das pesquisas com base na atividade
