| name | cache-auditor |
| description | Auditoria completa da infraestrutura de cache dos 3 ambientes — detecta stale, valida coerência, otimiza TTLs |
SKILL: Cache Auditor (Auditor de Cache)
Visão Geral
Skill especialista que vasculha e audita toda a infraestrutura de cache dos 3 ambientes do Super Cartola Manager. Detecta cache stale/morto, valida coerência com o código mais recente, e otimiza para velocidade suprema.
Filosofia: A verdade absoluta é a última alteração no código. Cache NUNCA sobrepõe a realidade. Alimenta-se de atualizações, descarta antiguidade.
Princípios Fundamentais
- Verdade = Código Atual — Cache serve o código, nunca o contrário
- Zero Cache Morto — Detecta e elimina cache stale, órfão e obsoleto
- Velocidade Suprema — Otimiza TTLs e estratégias para performance máxima nos apps
- Persistência — Salva resultados no MongoDB (
cache_auditorias) para histórico e comparação
- 3 Ambientes — Cobertura total: participante app, admin web, admin mobile app
3 Modos de Operação
| Comando | Ambiente | Alvo |
|---|
/cache-auditor CACHE-APP --participante | PWA Participante | Service Worker + IndexedDB (12 stores) + Memory Cache + Module Caches + App Version |
/cache-auditor CACHE-WEB --admin | Admin Desktop | CacheManager + Ferramentas Cache Admin + MongoDB Caches + Cache Invalidator |
/cache-auditor CACHE-APP --admin | PWA Admin Mobile | Service Worker + Runtime Cache + Pages API |
Arquitetura de Cache do Sistema (Mapa Completo)
┌─────────────────────────────────────────────────────────────────────────┐
│ SUPER CARTOLA - CACHE LAYERS │
├──────────────────┬──────────────────────┬──────────────────────────────┤
│ CACHE-APP │ CACHE-WEB │ CACHE-APP │
│ --participante │ --admin │ --admin │
├──────────────────┼──────────────────────┼──────────────────────────────┤
│ Service Worker │ (sem SW) │ Service Worker │
│ v18-copa-sc │ │ scm-admin-v1.0.0 │
├──────────────────┤ ├──────────────────────────────┤
│ IndexedDB │ CacheManager │ Runtime Cache │
│ SuperCartolaOff │ CartolaCache v1 │ scm-admin-runtime │
│ (12 stores) │ (6 stores) │ │
├──────────────────┤ ├──────────────────────────────┤
│ Memory Cache │ Admin Cache Tools │ Direct API Calls │
│ Map + IDB dual │ ferramentas-cache │ (pages/*.js) │
├──────────────────┤ ├──────────────────────────────┤
│ Module Caches │ │ │
│ rodadas/artil/ │ │ │
│ luva/pontos/etc │ │ │
├──────────────────┼──────────────────────┼──────────────────────────────┤
│ SERVER-SIDE (COMPARTILHADO) │
│ MongoDB Caches: extrato, ranking, top10, pontos-corridos, │
│ mata-mata, melhor-mes, capitao │
│ Cache Invalidator: cascata de dependências │
│ Cache Routes: universal + por módulo │
│ App Version: force-update por scope │
└─────────────────────────────────────────────────────────────────────────┘
Inventário de Arquivos por Modo
CACHE-APP --participante
| Camada | Arquivo | Tecnologia |
|---|
| Service Worker | public/participante/service-worker.js | Cache API (super-cartola-v18-copa-sc) |
| IndexedDB Offline | public/participante/js/participante-offline-cache.js | IDB SuperCartolaOffline v2 |
| Memory Cache | public/js/core/cache-manager.js | IDB CartolaCache + Map |
| Rodadas Cache | public/js/rodadas/rodadas-cache.js | Map (100 max, 5min) |
| Artilheiro Cache | public/js/artilheiro-campeao/artilheiro-campeao-cache.js | Map (100 max, 50MB) |
| Luva de Ouro Cache | public/js/luva-de-ouro/luva-de-ouro-cache.js | Map |
| Pontos Corridos Cache | public/js/pontos-corridos/pontos-corridos-cache.js | Map |
| Fluxo Financeiro Cache | public/js/fluxo-financeiro/fluxo-financeiro-cache.js | Map + cacheManager |
| App Version | public/js/app/app-version.js | localStorage |
CACHE-WEB --admin
| Camada | Arquivo | Tecnologia |
|---|
| CacheManager | public/js/core/cache-manager.js | IDB + Map (compartilhado) |
| Admin Cache Tools | public/js/ferramentas/ferramentas-cache-admin.js | Buttons manuais |
| Cache Invalidator | utils/cache-invalidator.js | Server-side cascading |
| Cache Routes | routes/cache-universal-routes.js | Express endpoints |
| Ranking Cache Routes | routes/ranking-geral-cache-routes.js | Express endpoints |
| Extrato Cache Routes | routes/extratoFinanceiroCacheRoutes.js | Express endpoints |
MongoDB Caches (Server-Side — todos os modos)
| Collection | Model | Propósito |
|---|
extratofinanceirocaches | models/ExtratoFinanceiroCache.js | Extrato financeiro consolidado |
rankinggeralcaches | models/RankingGeralCache.js | Ranking geral da liga |
top10caches | models/Top10Cache.js | Top 10 por rodada |
pontoscorridoscaches | models/PontosCorridosCache.js | Classificação pontos corridos |
matamatacaches | models/MataMataCache.js | Torneio mata-mata |
melhor_mes_cache | models/MelhorMesCache.js | Performance mensal |
capitao_caches | models/CapitaoCaches.js | Capitão de luxo |
Checklists de Auditoria
Modo 1: CACHE-APP --participante (26 checks)
Service Worker (6 checks)
- SW-01 Extrair
CACHE_NAME e verificar se corresponde à versão mais recente
- SW-02 Verificar se
STATIC_ASSETS está completo (comparar com arquivos reais em /participante/)
- SW-03 Confirmar estratégia fetch: API = NETWORK-ONLY, HTML = NETWORK-ONLY, static = NETWORK-FIRST
- SW-04 Verificar que
activate limpa caches antigos corretamente
- SW-05 Confirmar
skipWaiting() no evento install
- SW-06 Confirmar bypass de ES6 modules (fix v4.0 — mobile dynamic imports)
IndexedDB OfflineCache (6 checks)
- IDB-01 Cross-reference stores com módulos ativos de
modules-registry.json — detectar stores órfãos
- IDB-02 Validar TTLs: ranking/extrato < 1h durante temporada ativa; config/participante pode ser 24h
- IDB-03 Verificar lógica
TEMPORADA_ENCERRADA usa ParticipanteConfig.SEASON_STATUS corretamente
- IDB-04 Confirmar
DB_VERSION foi incrementado quando stores mudaram
- IDB-05 Verificar proteção de race condition (
_initPromise pattern)
- IDB-06 Validar que
cleanExpired() roda automaticamente e remove entries > 2x TTL
CacheManager (4 checks)
- CM-01 Extrair stores e TTLs do CacheManager
- CM-02 Detectar overlap/conflito entre CacheManager e OfflineCache
- CM-03 Verificar consistência de TTLs entre os dois sistemas
- CM-04 Confirmar eviction strategy e
cleanExpired automático
Module Caches (4 checks)
- MC-01 Scan
public/js/**/*cache*.js — inventariar todos os caches de módulo
- MC-02 Verificar TTLs razoáveis (dado frequência de atualização dos dados)
- MC-03 Verificar max entries e cleanup strategy de cada cache
- MC-04 Confirmar que
temporada está nos cache keys (segregação por temporada)
App Version (4 checks)
- AV-01 Verificar
CACHE_TTL e CHECK_INTERVAL_MS são razoáveis (mobile: 60s/300s)
- AV-02 Verificar que
limparCachesAntigos() identifica nomes de cache SW obsoletos
- AV-03 Cross-check
CURRENT_SW_CACHE hardcoded em app-version.js vs CACHE_NAME real no SW
- AV-04 Verificar que
version-scope.json inclui todos os arquivos relevantes do participante
Performance (2 checks)
- PERF-01 Estimar tamanho total de cache (stores x entries estimados)
- PERF-02 Detectar patterns N+1 (lista no cache, items individuais buscados separadamente)
Modo 2: CACHE-WEB --admin (12 checks)
Confirmação sem SW (2 checks)
- NSW-01 Verificar ausência de registro de Service Worker em arquivos HTML do admin
- NSW-02 Confirmar que é intencional (admin desktop sempre precisa de dados frescos)
CacheManager (4 checks)
- CM-01 Mesmos checks do participante (módulo compartilhado)
- CM-02 Verificar que páginas admin invalidam cache após operações de escrita
- CM-03 Verificar que admin não herda TTLs longos do participante
- CM-04 Confirmar cleanExpired automático
Admin Cache Tools (3 checks)
- ACT-01 Verificar que "Limpar IndexedDB" realmente limpa TODOS os databases relevantes
- ACT-02 Verificar que "RESETAR CACHE COMPLETO" dispara invalidação server-side
- ACT-03 Verificar que "RECALCULAR TUDO" tem confirmação e rate limiting
MongoDB Caches (3 checks)
- MDB-01 Para cada model de cache: verificar índices corretos e
temporada indexado
- MDB-02 Verificar
CACHE_DEPENDENCIES em cache-invalidator.js está completo (todos eventos cobertos)
- MDB-03 Verificar que TODAS operações de escrita nos controllers disparam invalidação
Modo 3: CACHE-APP --admin (12 checks)
Schema MongoDB — Collection cache_auditorias
{
modo: String,
data_auditoria: Date,
score_geral: Number,
score_por_categoria: {
service_worker: Number,
indexeddb: Number,
memory_cache: Number,
module_caches: Number,
mongodb_caches: Number,
invalidation: Number,
version_system: Number,
performance: Number
},
status: String,
achados: [{
codigo: String,
categoria: String,
severidade: String,
descricao: String,
arquivo: String,
linha: Number,
acao_recomendada: String,
auto_corrigivel: Boolean
}],
inventario: {
service_workers: [{
arquivo: String,
cache_name: String,
static_assets_count: Number,
estrategia: String
}],
indexeddb_stores: [{
db_name: String,
db_version: Number,
stores: [{
nome: String,
ttl_ms: Number,
ttl_legivel: String
}]
}],
memory_caches: [{
arquivo: String,
tipo: String,
max_entries: Number,
ttl_ms: Number
}],
mongodb_caches: [{
collection: String,
model: String,
indices: [String],
temporada_filtrada: Boolean
}]
},
cache_morto: [{
tipo: String,
descricao: String,
tamanho_estimado: String,
acao: String
}],
coerencia: {
sw_cache_name_sincronizado: Boolean,
indexeddb_stores_match_modules: Boolean,
ttls_consistentes: Boolean,
invalidation_chain_completa: Boolean,
version_system_ativo: Boolean
},
versao_skill: String,
duracao_auditoria_ms: Number,
auditor: String,
createdAt: Date,
updatedAt: Date
}
Índice recomendado: { modo: 1, data_auditoria: -1 }
Formato do Relatório de Saída
# AUDITORIA DE CACHE: CACHE-APP --participante
**Data:** 05/02/2026 14:30
**Modo:** CACHE-APP --participante
**Score Geral:** 82/100 (Bom)
**Status:** BOM
---
## Resumo por Categoria
| Categoria | Score | Checks | Status |
|-----------|-------|--------|--------|
| Service Worker | 5/6 | 83% | Atenção |
| IndexedDB | 6/6 | 100% | Excelente |
| Memory Cache | 3/4 | 75% | Atenção |
| Module Caches | 4/4 | 100% | Excelente |
| App Version | 3/4 | 75% | Atenção |
| Performance | 2/2 | 100% | Excelente |
---
## Achados
### ATENÇÃO (3 issues)
**[SW-03]** Service Worker: CURRENT_SW_CACHE em app-version.js não sincronizado
- Arquivo: public/js/app/app-version.js
- Valor hardcoded: `super-cartola-v17-module-fix`
- Valor real do SW: `super-cartola-v18-copa-sc`
- Ação: Atualizar CURRENT_SW_CACHE para valor correto
**[CM-02]** CacheManager: overlap com OfflineCache no store "ranking"
- CacheManager TTL: 10min
- OfflineCache TTL: 30min
- Ação: Unificar TTLs ou documentar razão da diferença
**[AV-03]** App Version: CURRENT_SW_CACHE desatualizado
- Mesmo issue do SW-03 (dependência)
---
## Cache Morto Detectado
| Tipo | Descrição | Ação |
|------|-----------|------|
| stale_sw_cache | `super-cartola-v17-module-fix` referenciado mas inexistente | Atualizar referência |
---
## Coerência
| Check | Status |
|-------|--------|
| SW cache name sincronizado | FALHA |
| IndexedDB stores = módulos | OK |
| TTLs consistentes | ATENÇÃO |
| Invalidation chain completa | OK |
| Version system ativo | OK |
---
**Salvo em:** cache_auditorias (MongoDB)
**Skill version:** 1.0.0
**Duração:** 4200ms
Severidades
| Nível | Critério | Ação |
|---|
| CRÍTICO | Cache servindo dados incorretos, SW bloqueando atualizações | Corrigir imediatamente |
| ALTO | TTLs muito longos para dados voláteis, invalidation chain quebrada | Corrigir antes do deploy |
| MÉDIO | Overlap de caches, stores órfãos, CDNs deprecados | Corrigir no sprint |
| BAIXO | Otimizações de performance, sugestões de melhoria | Backlog |
Quando Auditar
- Após alterar qualquer arquivo de cache — Validar coerência
- Após adicionar/remover módulo — Verificar stores IndexedDB
- Após atualizar Service Worker — Verificar CACHE_NAME e STATIC_ASSETS
- Antes de releases — Auditoria completa dos 3 modos
- Mensal — Detectar cache morto acumulado
Agnóstico de IA
Claude
/cache-auditor CACHE-APP --participante
/cache-auditor CACHE-WEB --admin
/cache-auditor CACHE-APP --admin
Outras IAs
Audite o cache do participante app usando o Cache Auditor skill
Requisito: IA deve ter acesso a Read, Grep, Glob e Bash para executar os checks.
Estrategias de Cache — Referencia Teorica (Novo - agnostic-core)
Referencia rapida para decisoes de cache no projeto.
Quando Usar Cache
| Cenario | Aplicar Cache? | Exemplo no Projeto |
|---|
| Dados lidos com frequencia, mudam raramente | SIM | Config de liga, regras, modulos ativos |
| Respostas de APIs externas | SIM | API Cartola (rodadas, mercado, atletas) |
| Computacoes pesadas deterministicas | SIM | Rankings, pontos corridos, extrato |
| Dados financeiros em operacao | NAO | Saldo durante transacao (usar banco) |
| Dados com requisito estrito de consistencia | NAO | Contagem de votos, resultados finais |
Estrategias Aplicadas no Projeto
| Estrategia | Descricao | Uso no SuperCartola |
|---|
| Cache-Aside | App busca no cache; se miss, busca no DB e preenche cache | NodeCache backend (rankings, rodadas) |
| TTL-Based | Cache expira apos tempo definido | Rodadas 5min, Rankings 10min, Configs 30min |
| Event-Driven Invalidation | Cache limpo quando evento ocorre | cache-invalidator.js — invalida cascata |
| Stale-While-Revalidate | Serve cache stale enquanto atualiza em background | Service Worker (participante PWA) |
TTLs Padrao (CLAUDE.md)
| Tipo de Dado | TTL | Justificativa |
|---|
| Rodadas | 5 min | Dados mudam durante jogos |
| Rankings | 10 min | Derivado de rodadas |
| Configs | 30 min | Mudam raramente |
| Mercado (API Cartola) | 5 min | Status muda periodicamente |
| Atletas (API Cartola) | 15 min | Escalacoes mudam no dia do jogo |
Armadilhas Comuns
| Armadilha | Problema | Solucao |
|---|
| Cache como fonte de verdade | Dado incorreto servido se cache corrompido | Banco SEMPRE prevalece; endpoint de recalculo |
| Thundering herd | Multiplos requests rebuildam cache ao mesmo tempo | Lock no rebuild; stale-while-revalidate |
| Cache sem TTL | Nunca expira, dado stale permanente | SEMPRE definir TTL explicito |
| Invalidacao em cascata falha | Cache de extrato nao atualiza quando ranking muda | Mapear dependencias em cache-invalidator.js |
| Cache por modulo sem liga_id | Dados de uma liga poluem cache de outra | TODA chave de cache inclui liga_id |
Comandos Uteis
grep -rn "ttl\|TTL\|maxAge\|max_age" --include="*.js" utils/ services/ config/ | grep -v node_modules
grep -rn "cache\.set\|cache\.get\|cacheKey" --include="*.js" . | grep -v "liga\|ligaId" | grep -v node_modules
grep -rn "invalidat\|clearCache\|flushCache" --include="*.js" utils/ services/
Ultima atualizacao: 2026-03-12
Versao: 2.0.0 (Enriquecido com estrategias de cache do agnostic-core)
Autor: Sistema Super Cartola Manager
