Dragon Fusion — Sessão Completa de Backend (v1)

Especificação consolidada para implementação do backend de produção, coerente com o escopo já definido do projeto: Puzzle + RPG leve, economia autoritativa, ranking sazonal, hatchery, evolução e LiveOps.

Princípios: servidor autoritativo para recursos críticos, idempotência por txnId, timers UTC, telemetria orientada a decisão, e baixo custo operacional para estúdio indie.

1) Objetivos do backend

Garantir integridade econômica (gold/gems/essência, claims, compras, revives, boosters).
Sincronizar progressão (mapa, estrelas, coleção, hatchery, evolução).
Operar competitivo assíncrono (mirror/ghost + leaderboard + season payout).
Suportar LiveOps sem deploy (missões, ofertas, eventos, multiplicadores).
Fornecer observabilidade para tuning (D1/D7, funis, fail reason, uso de magia/booster).

2) Arquitetura lógica (modular monolith v1)

Módulo	Responsabilidade	Autoritativo?
Auth	Identidade de player, sessão, refresh token, device binding	Sim
Profile	Nome, nível, XP, configurações, consentimento	Parcial
Economy	Carteira, gastos, créditos, ledger, antifraude	Sim
Progression	Mundos, fases, estrelas, unlocks, medalhas	Sim
Battle	Start/end de fase, validações de score, revive, boosters	Sim
Hatchery	Incubação, speed-up, claim, pity timer, duplicata→essência	Sim
Dragons	Coleção, níveis/tier, dragão ativo, skill unlock	Sim
Missions	Diárias/semanais, progress tracking, claim all	Sim
Leaderboard	Ranking, brackets, tiebreak, payout	Sim
Offers/IAP	Ofertas contextuais, validação de recibo Apple/Google	Sim
LiveOps	Config dinâmica por data/segmento	Sim
Analytics	Ingestão de eventos e agregações	N/A

Decisão v1: modular monolith (1 deploy) + filas internas. Evita complexidade prematura de microserviços.

3) Stack de infraestrutura recomendada

API: Node.js (Fastify/Nest) ou Go (Fiber) — foco em throughput e simplicidade.
Banco principal: PostgreSQL 16.
Cache/locks/ranking temporário: Redis.
Fila assíncrona: Redis Streams ou RabbitMQ (v1: Redis Streams).
Storage de replay/artefatos: S3 compatível.
Observabilidade: OpenTelemetry + Prometheus + Grafana + Loki.
Deploy: Docker + systemd/compose (v1), migrável para K8s no pós-scale.

4) Modelo de dados (núcleo)

4.1 Tabelas essenciais

Tabela	Campos-chave	Notas
players	player_id, created_at, status	Identidade base
player_profile	player_id, level, xp, language, settings_json	Dados de perfil
wallets	player_id, gold, gems, essence, energy_current, energy_last_tick_utc	Saldo autoritativo
economy_ledger	ledger_id, player_id, currency, amount, reason, txn_id, created_at	Auditoria financeira
player_progress	player_id, world, stage, stars_json, medals_json	Progresso e platina
battle_runs	run_id, player_id, stage_id, seed, started_at, ended_at, result, score	Rastro de fase
player_boosters	player_id, hint, undo, shuffle, turbo	Inventário de utilitários
hatch_slots	slot_id, player_id, egg_type, start_utc, end_utc, state	Incubação UTC
player_dragons	player_id, dragon_id, tier, level, active	Coleção/evolução
mission_state	player_id, mission_id, progress, target, claimed, reset_at	Missões
leaderboard_scores	season_id, player_id, score, updated_at	Ranking sazonal
season_rewards	season_id, player_id, bracket, reward_json, claimed	Payout final
iap_receipts	receipt_id, player_id, store, product_id, status, verified_at	Validação IAP
liveops_configs	config_key, version, payload_json, starts_at, ends_at	Config dinâmica

4.2 Índices e constraints críticos

UNIQUE(player_id, txn_id) em transações críticas (economy/claim/revive/iap).
UNIQUE(season_id, player_id) em payout de temporada.
CHECK(amount != 0) e validação de saldo mínimo no nível de serviço.
Índices por player_id, season_id, updated_at.

5) Contratos de API (v1)

5.1 Sessão e bootstrap

POST /v1/auth/guest → cria/retorna player + tokens
POST /v1/session/start → payload inicial da home
GET /v1/bootstrap → configs, versões, feature flags

5.2 Battle flow

POST /v1/battle/start (stageId, dragonId) → runId, seed, movesBase
POST /v1/battle/revive (runId, txnId, method) → movesGranted
POST /v1/battle/use-booster (runId, boosterType, txnId)
POST /v1/battle/end (runId, result, score, objectives, replayHash)

5.3 Progress, hatch, dragon

GET /v1/progress/map
POST /v1/hatch/start, /speedup, /claim
POST /v1/dragon/evolve, /set-active

5.4 Economy e liveops

GET /v1/wallet, GET /v1/ledger?cursor=
GET /v1/missions, POST /v1/missions/claim
GET /v1/offers/contextual
POST /v1/iap/verify
GET /v1/leaderboard/current, /season/reward

6) Regras críticas de consistência

Fluxo	Regra	Proteção
Claim recompensa	1x por condição	txnId + unique index
Reviver	max 3 por run	contador server-side + lock por run
Hatch timer	base UTC	ignorar relógio local
IAP	somente após verify	store API + dedupe receipt
Season reward	claim único	flag claimed + transação atômica

7) Segurança e antifraude v1

JWT curto + refresh rotativo + fingerprint de device.
Rate limit por IP + por player em rotas sensíveis.
Replay hash em /battle/end para detecção de score improvável.
Heurísticas: score/minuto, uso de revive anômalo, spikes de moeda.
Filas de revisão para contas suspeitas (não bloquear automaticamente no v1).

8) Telemetria e KPIs operacionais

8.1 Eventos obrigatórios

session_start, level_start, level_end, magic_used, booster_used, revive_offer_shown, revive_accept, hatch_complete, purchase_success, mission_claim.

8.2 Dashboards de decisão

Funil tutorial → fase 5 → fase 15.
Win/fail por fase + fail reason.
Uso de magia por mundo (target >= 1.2/fase).
Revive per session (target <= 1.8).
D1/D7, ARPDAU, conversão de oferta contextual.

9) Operação de LiveOps

9.1 Entidades liveops

MissionSet: diárias/semanais por segmento.
OfferSet: ofertas com cooldown/cap.
EventRule: multiplicadores de drop, score, energia.
SeasonConfig: janela, tiebreak, brackets, rewards.

9.2 Guardrails

Publicação com versionamento e rollback em 1 clique.
Janela de ativação UTC e validação de conflito de regras.
Dry-run antes de publicar em produção.

10) SLOs e confiabilidade

Métrica	Meta v1
Disponibilidade API	99.5%
P95 latência (GET)	< 180ms
P95 latência (POST crítico)	< 280ms
Erro 5xx	< 0.5%
Perda de evento analytics	< 1%

11) Roadmap backend em 3 fases

Fase A — MVP estável (2–4 semanas)

Auth/Profile/Economy/Battle/Hatch/Dragons/Missions.
Idempotência total + ledger + timers UTC.

Fase B — Soft launch operável (2–3 semanas)

Leaderboard/Season/Offers/IAP verify.
LiveOps básico + dashboards de operação.

Fase C — Escala inicial (3+ semanas)

Antifraude aprimorado + otimizações de ranking.
Particionamento de dados quentes e cold storage.

12) Riscos e mitigação

Risco	Impacto	Mitigação
Duplicação de recompensa	Alto	txnId + transação serializável + testes de concorrência
Exploit de relógio	Alto	UTC servidor em energia/hatch/evento
Fraude de score	Médio/Alto	replayHash + regras de plausibilidade
Quebra por config liveops	Médio	schema validation + dry-run + rollback
Custo infra acima do esperado	Médio	cache agressivo + batching + compressão

13) Checklist de prontidão backend (go/no-go)

100% rotas críticas com idempotência.
Teste de corrida (concorrência) passando em claims/revive/iap.
Leaderboard fechado com tiebreak determinístico.
Painel liveops com rollback validado.
Alertas de erro/latência/fraude ativos.

← Voltar ao Hub