# Aurum Poker 0.7 — multiplayer local

## O que esta versão faz

- Contas locais por apelido e senha de teste, com 10.000 fichas gratuitas.
- Lobby com ocupação real do servidor local, oito mesas independentes.
- Texas Hold’em No-Limit de 2 a 8 jogadores, cartas embaralhadas no servidor, turnos, apostas, all-ins, potes paralelos, avaliação, empates e devolução de excesso.
- Comandos com ID, validação de revisão, processamento ordenado, confirmação e reenvio da mesma intenção após reconexão.
- Reserva/retorno de fichas de teste e histórico das últimas 100 mãos do próprio jogador.
- Estado persistente criptografado, recuperação de mão após reiniciar o servidor, timeout de 30 segundos e bloqueio de dois escritores contra o mesmo banco.
- Visual azul-escuro/violeta. Desistir vermelho, passar/pagar azul, apostar/aumentar verde. Cor é acompanhada de texto/ícone. Preferências de som, redução de movimento e confirmação de aposta alta.

Ainda não é plataforma de operação monetária: não há depósitos, saques, PIX, ledger de partidas dobradas, MFA/RBAC administrativo, recuperação por e-mail, KYC, limites/autoexclusão efetivamente aplicados nem análise jurídica. Sem bots. A versão atual do multiplayer é local; o endereço Sites publicado anteriormente continua sendo a primeira demonstração.

## Antes de começar no Windows

1. Mantenha Node.js 22 x64 instalado. `node -p "process.arch"` deve retornar `x64`.
2. Extraia o NOVO ZIP em uma pasta separada, por exemplo `Downloads\aurum-poker-v7`. Não execute dentro do ZIP nem misture com a pasta antiga.
3. Feche o servidor da versão antiga com Ctrl+C para liberar a porta 5173.

### Maneira simples

Abra a pasta extraída e dê dois cliques em **INICIAR-AURUM.cmd**. Ele instala as dependências, prepara o servidor e abre os dois serviços no mesmo terminal. A instalação precisa de internet. Aguarde aparecer o endereço da interface e a mensagem “servidor multiplayer de TESTE pronto”. Deixe a janela aberta.

Esse arquivo foi escrito para Windows, mas não executado em uma máquina Windows nesta entrega. Se ocorrer erro, envie a última mensagem do terminal.

### Alternativa pelo CMD

Dentro da pasta do projeto, clique na barra de endereço, digite `cmd` e pressione Enter. Execute UM POR VEZ, só continuando se o anterior terminar sem erro:

```cmd
npm ci
npm run preparar
npm run jogar
```

Depois abra **http://localhost:5173**. `npm run jogar` inicia interface e servidor; `npm run dev` sozinho continua abrindo apenas a interface, sem jogo.

Nas próximas vezes, basta `npm run jogar` (ou INICIAR-AURUM.cmd, que refaz a instalação). Ctrl+C encerra os serviços. Não execute duas cópias ao mesmo tempo.

## Primeira partida no mesmo computador

1. Em http://localhost:5173, crie uma conta de teste. Use apelido e senha exclusiva de pelo menos 10 caracteres. Não use senha bancária ou de e-mail.
2. No lobby multiplayer, escolha **Trancoso (heads-up)**.
3. Escolha 500 fichas e clique **Sentar e reservar fichas**.
4. Abra uma janela anônima: Ctrl+Shift+N no Chrome/Edge. Nela, abra o mesmo endereço e crie OUTRA conta. Abas normais compartilham a conta; é necessário perfil/janela anônima separado.
5. Entre também em Trancoso com 500 fichas.
6. Nas DUAS janelas clique **Estou pronto para jogar**. Assim que dois jogadores estiverem prontos, a mão começa.
7. Alterne as janelas: só os botões do jogador da vez ficam habilitados. Use pagar/passar para chegar ao showdown, ou teste desistir e aumentar.
8. Ao terminar, a próxima mão começa automaticamente após 5 segundos (ou após a apresentação das múltiplas sequências e mais 5 segundos) se houver pelo menos dois jogadores ativos e conectados. Em Opções, use Pausar para ficar fora das próximas mãos; Estou pronto reativa sua participação. Não há recarga automática.
9. Teste Sair e devolver fichas; durante a mão, a saída fica agendada e é liquidada depois. Recarregue somente entre mãos.

## Jogar no celular e computador na mesma rede

1. Deixe o servidor iniciado no computador. Computador e celular precisam estar no mesmo Wi-Fi/rede local confiável.
2. No CMD do computador, execute `ipconfig` e encontre Endereço IPv4 do adaptador conectado, por exemplo `192.168.1.15` (use o seu valor real).
3. No celular, abra `http://SEU-IP:5173`, por exemplo `http://192.168.1.15:5173`.
4. Se o Windows perguntar sobre firewall, permita Node.js SOMENTE em redes privadas. São usadas as portas 5173 (interface) e 4000 (jogo). Não abrir portas no roteador nem liberar redes públicas.
5. Crie uma segunda conta no celular e entre na mesma mesa. Use senhas exclusivas de teste: a rede local utiliza HTTP sem TLS.

O servidor permite origens http://localhost:5173 e IPs privados nas portas 5173/4173. Se a interface escolher outra porta por conflito, feche a versão antiga para usar 5173. Outro jogador fora da rede doméstica depende de hospedagem HTTPS/WSS; não é preciso contratar nada para este teste local.

## Onde ficam os dados

`backend/data/` guarda banco PostgreSQL embarcado PGlite, chave local e estado do jogo. Essa pasta é ignorada pelo Git e não vem no ZIP. Não apagar ou compartilhar: nela ficam contas, senhas com scrypt e dados de teste. A chave local permite abrir os snapshots; guarde-a junto com o banco em um backup de desenvolvimento, mas separada em produção.

Após encerramento normal, reiniciar carrega o mesmo baralho/mão e o prazo anterior. Após uma queda abrupta, o bloqueio do banco pode levar cerca de 30 segundos para expirar: espere antes de iniciar de novo. Não remova manualmente o bloqueio enquanto outra instância estiver viva.

Esta persistência é uma transação global de estado de TESTE, com controle de revisão. Ela não é um ledger financeiro nem uma arquitetura de alta disponibilidade. Uma falha ao confirmar gravação não deve ser tratada como aposta aceita. Não apostar dinheiro com este software.

## Regras desta versão

- Rake 0%, fichas inteiras sem valor. Guarujá mantém entrada 200–1.000 fichas; demais mesas 20–100 BB. Nunca comprar ou converter fichas.
- Dealer automático por mesa; botão móvel entre os participantes prontos para cada mão. Heads-up: botão/SB primeiro pré-flop, BB primeiro pós-flop. Retorno do sit-out nesta versão de teste é por Estou pronto; política de blinds perdidos de cash monetário ainda precisa ser implementada/revisada.
- Baralho Fisher–Yates com crypto.randomInt; duas cartas privadas e burn antes de cada rua. Não há ferramenta para escolher cartas em partida real do servidor.
- Aumento mínimo por último incremento completo; all-in menor não reabre isoladamente, mas incrementos acumulados podem reabrir.
- Showdown: todas as mãos que não desistiram são abertas. Vitória por fold não revela cartas alheias. Histórico do usuário mostra suas próprias cartas e resultado textual.
- Empate: ficha indivisível começa pelo vencedor à esquerda do botão, em sentido horário. Aposta não igualada volta ao apostador. Nenhum rake escondido.
- Prazo 30 segundos: check se possível, fold caso contrário. Marca sit-out para próximas mãos. Reconectar não renova tempo. O relógio visual usa a diferença entre a hora do aparelho e a hora recebida do servidor; prazo e ação são decididos pelo servidor.
- Saída solicitada no meio da mão é agendada; não força fold nem elimina elegibilidade. Pausa, desconexão e timeout suspendem a participação nas próximas mãos até marcar pronto outra vez.
- Uma conta fica em uma mesa por vez nesta versão.

## Tecnologias e limites de validação

Backend NestJS 11 (versões exatas no backend/package-lock.json), Node.js, WebSocket ws, criptografia nativa; banco PGlite local baseado em PostgreSQL. Existe adaptador `pg` para PostgreSQL externo por DATABASE_URL, com advisory lock de escritor único, mas esse adaptador externo não foi executado nesta entrega. Sem Redis por enquanto.

Frontend React/TypeScript/Tailwind com Vinext beta herdado do ambiente Sites. Sem migração silenciosa para Next.js nativo. O backend roda separado do Cloudflare Worker. A interface desta versão só conecta automaticamente em localhost/IP privado por HTTP; um ambiente público exigirá configuração explícita HTTPS/WSS, origens e cookies Secure, mais os controles pendentes.

Fontes consultadas: https://pglite.dev/docs/ ; https://docs.nestjs.com/first-steps ; https://nodejs.org/api/crypto.html#cryptorandomintmin-max-callback . Essas referências não certificam segurança, justiça nem adequação jurídica da implementação.

## Testes

```cmd
npm run test:poker
```

Suite com regras do motor, 300 mãos com conservação de fichas, persistência, exclusão de escritor, comandos duplicados, reservas concorrentes, HTTP e dois WebSockets reais, visões privadas, reconexão e revogação de sessão. Consulte VALIDACAO.md para resultados e limitações. Não houve inspeção em navegador ou em Windows/celular físicos nesta entrega.

### Docker opcional

`docker compose up --build` inicia somente o backend de teste na porta 4000 e conserva dados em volume. Execute a interface separadamente com `npm run dev` na porta 5173. Não execute `npm run jogar` ao mesmo tempo que esse backend Docker, pois a porta 4000 estará ocupada. O caminho recomendado neste estágio é o .cmd, sem Docker. O compose não foi executado nesta entrega.

## Atualização 0.4 e teste das novidades

Extraia em pasta nova e inicie normalmente. Para preservar suas contas, com TODOS os servidores encerrados, copie a pasta backend/data inteira da versão anterior para backend/data na nova pasta antes de iniciar. Preserve também a pasta antiga como backup; não copie node_modules. Nunca copie o banco enquanto estiver rodando. Sem essa cópia, a pasta nova cria contas de teste independentes.

As mesas novas são adicionadas ao carregar um banco anterior. Jardins passa a oito lugares se não existir mão em andamento; caso esteja ativa, termine essa mão e reinicie para atualizar sua capacidade. Guarujá já nasce com oito lugares.

No lobby escolha Jardins para Hold’em 8-max, ou Guarujá para Omaha 5 Pot-Limit 8-max. Copacabana oferece Omaha 5 com seis lugares. Duas pessoas já podem iniciar qualquer mesa; oito é a capacidade máxima. Cada participante precisa de conta própria. Na lateral direita, abra uma mão encerrada; no celular toque no relógio de histórico. A partida atual e seu prazo continuam normalmente. Cartas descartadas não são reveladas, mesmo depois da mão. Registros de versões antigas continuam disponíveis, mas não ganham retroativamente detalhes que não foram salvos.

### Regras pesquisadas em 10/09/2026

Texas Hold’em NL: https://www.pokerstars.com/poker/games/texas-holdem/
Omaha 5: https://www.pokerstars.com/poker/games/omaha/5-card/

No-Limit não limita a quantidade de raises, mas cada raise precisa respeitar o incremento mínimo e o stack. All-in insuficiente não reabre isoladamente a quem já agiu; aumentos curtos acumulados podem reabrir ao alcançar o incremento completo.

Omaha 5 High Pot-Limit: cinco privadas, exatamente duas privadas e três do board na melhor mão. Teto total na rua = aposta já colocada pelo jogador + valor a pagar + pote atual (incluindo apostas) + valor a pagar, limitado pelo stack. Com blinds 5/10 em heads-up, o primeiro aumento máximo é para 30; em mesa cheia sem limpers é para 35. O atalho Máximo só vira All-in quando todo o stack pode ser apostado legalmente. O servidor rejeita valores fora dos limites.

Oito jogadores de Omaha usam 40 cartas privadas + 5 comunitárias + 3 descartes de distribuição, sobrando 4 no baralho. As sequências extras só são oferecidas quando houver cartas suficientes no baralho.

## Regras de casa 0.5 — Guarujá e acordo de sequências

Guarujá usa somente a aposta obrigatória do dealer de 5, com teto TOTAL pré-flop de 5 por jogador. Não há cobrança adicional de small/big blind. A ação começa à esquerda do D; o D já pagou e não precisa confirmar outra aposta. Os demais pagam 5 ou desistem; ninguém aumenta nessa rua. Se todos desistirem, a contribuição volta integralmente ao D, sem flop. Com pagadores, abre o flop; daí em diante o mínimo é 5 e o máximo segue Pot-Limit. O botão gira entre participantes elegíveis. Stack abaixo de 5 exige recarga manual antes de voltar.

Copacabana segue o Omaha 5 Pot-Limit padrão. O acordo de múltiplas sequências existe em AMBAS as mesas Omaha quando restam exatamente dois jogadores não desistentes e não há mais apostas possíveis por causa do all-in, antes de completar o river. Mais de dois jogadores disputando continuam com uma sequência nesta versão.

A escolha acontece antes de revelar as cartas restantes. Prazo único de 30 segundos pelo servidor; ambos escolhem 2 para duas, ou ambos 3 para três. Qualquer 1 ou desconexão resolve em uma sequência. Escolhas diferentes permanecem em negociação até os dois concordarem ou acabar o prazo; sem consenso ao final, segue uma sequência. Reiniciar o servidor preserva o acordo e o prazo; se os participantes não estiverem reconectados no processamento da recuperação, resolve em uma. Não existe escolha administrativa ou privilégio de quem está à frente.

Somente as ruas restantes são repetidas, mantendo as cartas comunitárias já abertas. As cartas saem do mesmo baralho, sem reposição, incluindo os descartes de distribuição; cartas de quem desistiu não retornam ao baralho. Cada sequência inclui seus próprios burns. A quantidade disponível é calculada pelo servidor: com oito jogadores de Omaha distribuídos, não cabem duas sequências completas pré-flop; no flop podem caber duas sequências de turn+river; no turn podem caber três rivers. As cartas ocultas não são enviadas durante o acordo.

Cada pote contestado é dividido igualmente pelo número de sequências antes da comparação. Cada parte é avaliada com exatamente duas privadas e três comunitárias. Empate divide a parte entre vencedores elegíveis. Fichas indivisíveis na divisão entre sequências vão primeiro à sequência 1, depois 2; dentro de cada sequência, aos vencedores em ordem horária à esquerda do D. Aposta não igualada volta ao dono antes da divisão. Exemplo: 300 em três partes = 100 por resultado; vencer dois rende 200 e vencer três rende 300. Com 200, as partes são 67, 67 e 66.

No resultado, use os botões Sequência 1/2/3 para ver cada board. O histórico guarda todos os boards, as melhores cinco cartas mostradas e a distribuição por pote. Os saldos são atualizados uma vez pela transação do servidor, independentemente da animação ou do board selecionado.

### Testar em dois aparelhos

1. Pare a versão anterior e extraia a v5 em pasta nova. Copie backend/data inteiro apenas com o servidor fechado para preservar contas; guarde a pasta anterior como backup. Abra INICIAR-AURUM.cmd na pasta nova.
2. Entre na Guarujá com duas contas. Clique Estou pronto; confirme que apenas D colocou 5 e o outro pode pagar 5 ou desistir. Desista para conferir devolução e rotação. Na mão seguinte, pague para abrir flop e conferir aumentos Pot-Limit.
3. Para testar acordo, depois do flop faça aumentos legais até um all-in ser pago. Com dois participantes, ambos verão 1/2/3 (conforme baralho). Escolham 3 nos dois aparelhos e confira as três sequências e o histórico. Repita escolhendo 2/3: as duas propostas ficam visíveis; um pode ajustar sua escolha para chegar ao consenso. Se ninguém ajustar antes do prazo, sai uma sequência. Escolher 1 encerra imediatamente em uma sequência.
4. Não mantenha duas versões do servidor rodando. Atualizações de regras da Guarujá valem na próxima mão; uma mão anterior recuperada é concluída com sua configuração original.

## Atualização 0.7 — ritmo e propostas visíveis

As decisões de jogo e o acordo têm 30 segundos. O acordo exibe o nome e a proposta de cada participante. Escolher 2/3 não é uma aposta no que o outro escolheu: ambos veem as escolhas, podem alterá-las e o botão oferece Aceitar quando coincide com a proposta do adversário. A seleção Uma vez continua sendo recusa imediata. Modificar proposta não renova o prazo.

Ao fechar três sequências, a primeira fica 10 segundos, a segunda 5 e a terceira 5. Duas sequências mantêm 30 segundos cada. Depois da apresentação, há uma pausa final de 5 segundos para a próxima mão: total de 25 segundos para três e 65 segundos para duas. Mãos comuns têm pausa de 5 segundos. As cartas anteriores sobem para miniaturas; as novas ocupam o espaço principal. Pausa, saída e recarga continuam disponíveis. Os botões de revisão habilitam cada sequência quando ela é apresentada. Acompanhar apresentação retorna ao avanço automático.

A animação não segura o pagamento: o servidor confirma os resultados e saldos de todas as sequências de uma vez; o histórico já pode ser consultado. O cronograma usa completedAt do servidor, portanto reconectar não reinicia a apresentação. Redução de movimento mantém a sequência temporal e retira o movimento de subida.

A v7 é um pacote completo. Feche os servidores antigos, extraia em pasta nova e copie backend/data inteiro da versão anterior somente com o servidor parado. Inicie INICIAR-AURUM na pasta nova. Não é necessário aplicar os patches antigos separadamente. Mãos ou prazos já iniciados antes da atualização conservam o horário persistido; os novos intervalos entram nas próximas mãos.