Guia de Migração e Diagnóstico de Presets¶

Problema Identificado¶

Os presets estavam sendo armazenados apenas em memória no Durable Object. Quando o Durable Object era reiniciado (eviction), todos os presets eram perdidos, causando:

Perda de presets após inatividade
Inconsistência entre local (127.0.0.1) e produção (rodrigonahum.com.br)
Presets antigos reaparecendo misteriosamente (cache local sobrescrevendo nuvem vazia)

Solução Implementada¶

✅ Persistência em Durable Object Storage: Todos os presets agora são salvos em storage persistente ✅ Carregamento automático: Presets são carregados do storage na inicialização do DO ✅ Versionamento robusto: Comparação de versões por preset e por enhancer global ✅ Logs de diagnóstico: Rastreamento completo de todas as operações ✅ Endpoints de diagnóstico: Ferramentas para verificar o estado dos presets

Endpoints Disponíveis¶

1. Diagnóstico de Presets¶

GET https://settings-sync.rnahumaf.workers.dev/debug/presets
Authorization: Bearer <seu-token-jwt>

Retorna informações detalhadas sobre:

Presets em memória
Presets em storage persistente
Contagem e nomes de presets por branch

2. Migração de Dados¶

POST https://settings-sync.rnahumaf.workers.dev/migrate/presets
Authorization: Bearer <seu-token-jwt>

Migra presets do formato antigo (KV cloudBranchesV1) para o novo formato (DO storage por branchKey).

3. Leitura de Presets (já existente)¶

GET https://settings-sync.rnahumaf.workers.dev/v2/presets
Authorization: Bearer <seu-token-jwt>
X-Branch-Key: v2|GLOBAL|/|[email protected]|nome-do-branch

4. Gravação de Presets (já existente)¶

PUT https://settings-sync.rnahumaf.workers.dev/v2/presets
Authorization: Bearer <seu-token-jwt>
X-Branch-Key: v2|GLOBAL|/|[email protected]|nome-do-branch
Content-Type: application/json

{
  "localPresets": { ... },
  "presetOrder": [ ... ],
  "favoriteSystemPresetsOrder": [ ... ],
  "activePresetName": "...",
  "presetMeta": { ... },
  "enhancerGlobal": { ... }
}

Passo a Passo para Migração¶

1. Verificar Estado Atual¶

# Local (127.0.0.1)
curl -H "Authorization: Bearer SEU_TOKEN" \
  http://127.0.0.1:8788/debug/presets

# Produção (rodrigonahum.com.br)
curl -H "Authorization: Bearer SEU_TOKEN" \
  https://settings-sync.rnahumaf.workers.dev/debug/presets

2. Executar Migração (se necessário)¶

# Local
curl -X POST \
  -H "Authorization: Bearer SEU_TOKEN" \
  http://127.0.0.1:8788/migrate/presets

# Produção
curl -X POST \
  -H "Authorization: Bearer SEU_TOKEN" \
  https://settings-sync.rnahumaf.workers.dev/migrate/presets

3. Verificar Novamente¶

curl -H "Authorization: Bearer SEU_TOKEN" \
  https://settings-sync.rnahumaf.workers.dev/debug/presets

Testando a Persistência¶

Via Preset Inspector¶

Abra docs/md/llm/admin/presets-inspector.html
Clique em "Verificar token" para confirmar autenticação
Clique em "Atualizar dados" para carregar branches
Selecione cada branch e verifique se os presets aparecem
Aguarde alguns minutos e recarregue - os presets devem persistir

Via Console do Navegador¶

// Obter token
const token = localStorage.getItem('auth_token');

// Verificar estado de diagnóstico
fetch('https://settings-sync.rnahumaf.workers.dev/debug/presets', {
    headers: { Authorization: 'Bearer ' + token },
})
    .then((r) => r.json())
    .then((d) => console.log('Debug:', d));

// Executar migração
fetch('https://settings-sync.rnahumaf.workers.dev/migrate/presets', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + token },
})
    .then((r) => r.json())
    .then((d) => console.log('Migration:', d));

Formato de BranchKey¶

O formato do branchKey é:

v2|<SCOPE>|/|<email>|<branch-name>

Exemplos:

v2|GLOBAL|/|[email protected]|cel1
v2|GLOBAL|/|[email protected]|pc4
v2|GLOBAL|/|[email protected]|default

Logs Importantes¶

Procure por estes logs no console do Cloudflare:

[settings-sync][do:loadPresets] - Carregamento inicial
[settings-sync][do:savePreset] - Salvamento em storage
[settings-sync][do:presets:get:hit] - Leitura com sucesso
[settings-sync][do:presets:put:success] - Escrita com sucesso
[settings-sync][do:migrate] - Migração de dados

Troubleshooting¶

Erro 404 ao buscar presets¶

O branch ainda não foi inicializado no DO storage
Execute a migração ou salve presets pelo site principal

Erro 500 ao salvar presets¶

Verifique os logs do Cloudflare Workers
Pode ser erro de serialização ou storage cheio

Presets aparecem e desaparecem¶

Certifique-se de que a migração foi executada
Verifique se há múltiplas instâncias DO conflitantes
Confirme que o branchKey está correto

Diferenças entre local e produção¶

Execute migração em ambos os ambientes
Verifique se os branchKeys estão idênticos
Confirme que o mesmo usuário está autenticado

Monitoramento Contínuo¶

Após a migração, monitore:

Preset Inspector: Deve mostrar todos os branches com seus presets
Logs do Worker: Não deve haver erros 404/500 em operações de preset
Consistência: Local e produção devem ter os mesmos presets

Notas Técnicas¶

Storage Persistente: Usa Durable Object Storage (persiste indefinidamente)
Lazy Loading: Storage é carregado na primeira requisição (não no constructor)
Atomic Operations: Usa blockConcurrencyWhile para evitar race conditions
Versionamento: Cada preset tem versão de 6 segmentos (a.b.c.d.e.f)
Rollback Automático: Se salvar em storage falhar, remove da memória