Escopo e PRD: App móvel para lojas + PWA de apostas esportivas
Versão 1.0 · Documento de rascunho para decisão do dono
Dados e números de exemplo são fictícios e estão marcados como tal.
1. Resumo executivo
Dois produtos com um backend comum:
- App móvel para lojas (Kodz Lojas): app nativo (iOS e Android) para o lojista gerir a loja: vendas, estoque, caixa, pedidos e financeiro, com o painel do resultado líquido.
- PWA de apostas esportivas (Kodz Apostas): aplicativo web instalável, para o apostador fazer apostas esportivas, com carteira, histórico e jogo responsável.
Ponto crítico: apostas de quota fixa no Brasil são reguladas pela Lei 14.790/2023 e pela Secretaria de Prêmios e Apostas (SPA/Ministério da Fazenda). Operar a PWA exige licença de operador (ou parceria com operador licenciado), CNPJ e regras de verificação de idade, PLD/KYC e publicidade. Este PRD trata a PWA como front-end de um operador licenciado. Nenhuma operação de apostas deve ir ao ar antes de validação jurídica.
2. Objetivos e métricas
| Objetivo | Métrica | Meta inicial (fictícia) |
|---|
| Lojista controlar a loja pelo celular | % de vendas registradas no app | 90% em 60 dias |
| Lojista ver resultado líquido | Tempo para ver o resultado do dia | menos de 3 toques |
| Apostador fazer aposta com segurança | Taxa de conclusão de aposta | 70% dos iniciados |
| Jogo responsável | Limites ativos por usuário | 100% dos usuários com limite configurado antes da 1ª aposta |
3. Público
- Lojista: dono ou gerente de loja pequena e média, usa celular como principal ferramenta, pouco tempo para planilhas.
- Apostador: maior de 18 anos, verificado, usa celular, aposta em futebol e outros esportes, com interesse em rapidez e clareza das odds.
- Administrador (interno): equipe do Kodz ou do operador, gerencia cadastros, limites, KYC e relatórios.
4. Escopo
4.1 Incluído (v1)
App Kodz Lojas (iOS e Android)
- Login com e-mail/telefone e 2FA.
- Cadastro da loja (dados, CNPJ, horário).
- Produtos e estoque: cadastro com foto, preço, custo, quantidade mínima e alerta de ruptura.
- Vendas: registro rápido no caixa, forma de pagamento, desconto e cancelamento com motivo.
- Compras: registro de compra com fornecedor, data, valor e documento anexado.
- Custos e despesas por categoria, com comprovante.
- Painel: vendas do dia e do mês, lucro líquido (vendas − custo dos produtos − despesas), gráficos simples.
- Relatórios exportáveis em PDF e CSV.
- Modo offline para venda, com sincronização ao voltar a conexão.
- Notificações push: estoque baixo, venda cancelada, resumo diário.
PWA Kodz Apostas (web instalável, sem loja de apps)
- Instalação na tela inicial (manifest, service worker, ícones).
- Cadastro com verificação de idade (18+) e KYC (documento e CPF) via provedor terceirizado.
- Carteira: depósito e saque por PIX, com limites e histórico. Pagamentos reais só com provedor licenciado.
- Esportes e eventos com odds, busca e favoritos.
- Tipos de aposta: simples e múltipla. Cálculo de retorno antes de confirmar.
- Apostas em aberto e histórico com status (ganha, perdida, anulada, cash-out se o operador oferecer).
- Limites de jogo responsável: depósito, perda, tempo de sessão, autoexclusão, pausa.
- Mensagens de jogo responsável e canal de ajuda em toda tela de aposta.
- Notificações web push de resultado e promoções (com opt-in).
Backend e administração (comum aos dois)
- API única com autenticação, perfis (lojista, apostador, admin), auditoria de transações.
- Painel administrativo: usuários, KYC, limites, bloqueios, relatórios de apostas e de vendas.
- Integração com feed de odds e resultados (fornecedor terceirizado).
4.2 Fora do escopo (v1)
- Cassino, jogos de azar e apostas em tempo real com streaming de vídeo.
- Operação própria de quota fixa sem licença.
- Marketplace entre lojas.
- Emissão de nota fiscal (integração futura com emissor).
- Programa de afiliados e influenciadores.
- Apostas em outros países.
5. Perfis de usuário e permissões
| Perfil | Pode | Não pode |
|---|
| Lojista | Gerir produtos, vendas, compras, despesas, relatórios da própria loja | Ver dados de outra loja, mexer em apostas |
| Apostador | Depositar, apostar, sacar, ver histórico, definir limites | Apostar sem KYC, ver dados de outros usuários |
| Admin | Gerenciar cadastros, KYC, limites, bloqueios | Alterar resultados de eventos sem trilha de auditoria |
6. Requisitos funcionais (principais)
Lojista
- RF-L01: cadastrar produto com foto, SKU, preço, custo e estoque mínimo.
- RF-L02: registrar venda em até 3 toques, com itens, desconto e pagamento.
- RF-L03: cancelar venda exige motivo e fica no histórico.
- RF-L04: alerta push quando estoque ≤ mínimo.
- RF-L05: painel mostra receita, custo, despesas e lucro líquido do período.
- RF-L06: exportar relatório em PDF e CSV.
- RF-L07: funcionar offline e sincronizar sem perda de vendas.
Apostador
- RF-A01: cadastro com idade ≥ 18 e KYC antes de apostar.
- RF-A02: definir limites de depósito, perda e tempo antes da primeira aposta.
- RF-A03: listar eventos com odds atualizadas; odds mudam com aviso antes de confirmar.
- RF-A04: montar bilhete simples ou múltiplo e ver o retorno potencial.
- RF-A05: confirmar aposta somente com saldo suficiente e limites não excedidos.
- RF-A06: histórico com status e extrato da carteira.
- RF-A07: autoexclusão e pausa com efeito imediato.
- RF-A08: instalar a PWA na tela inicial.
Administração
- RF-AD01: revisar KYC e aprovar, recusar ou pedir documentos.
- RF-AD02: bloquear conta com motivo, trilha de auditoria.
- RF-AD03: lançar resultado de evento com dupla confirmação.
7. Requisitos não funcionais
- Desempenho: tela de venda responde em até 300 ms; lista de odds atualiza em até 2 s.
- Disponibilidade: 99,5% mensal no backend; apostas fora do ar mostram aviso claro, sem aceitar aposta.
- Segurança: HTTPS, senhas com hash forte, 2FA para lojista e admin, segredos fora do código, logs sem dados sensíveis.
- Privacidade: LGPD. Coleta mínima, consentimento, exportação e exclusão de dados do titular.
- Acessibilidade: contraste 4,5:1, alvos de toque de 44 px, texto ampliável.
- PWA: Lighthouse acima de 90 em desempenho e PWA; funciona com cache offline só da tela de conta e histórico.
- Compatibilidade: iOS 16+ e Android 10+; navegadores atuais (Chrome, Safari, Edge).
- Retenção de registros: transações e apostas pelo prazo exigido pela regulação e pela Receita (validar com jurídico).
8. Regras de negócio
- Aposta só é aceita com odds vigentes, saldo disponível e limites respeitados.
- Evento sem resultado oficial não é liquidado. Anulação segue as regras publicadas.
- Lançamento de resultado exige dupla confirmação e fica auditado.
- Lucro do lojista = vendas − CMV (custo dos produtos vendidos) − despesas do período.
- Venda cancelada reverte estoque e receita, sem apagar o registro.
- Jogo responsável: limite só pode ser aumentado após 24 h; diminuir vale na hora.
9. Jornadas principais
Lojista (venda): abrir app → Vender → buscar produto ou ler código → quantidade → pagamento → concluído, estoque baixa e painel atualiza.
Apostador (aposta): abrir PWA → cadastro com KYC → definir limites → depositar via PIX → escolher evento e odd → montar bilhete → ver retorno → confirmar → acompanhar em Minhas apostas.
10. Arquitetura (proposta)
- App Lojas: Expo (React Native), SQLite local para offline, sincronização com a API.
- PWA Apostas: React/Vite com service worker e manifest.
- API: Node.js ou Python com PostgreSQL; filas para eventos (resultados, notificações).
- Serviços terceiros: provedor de KYC, provedor de PIX e carteira do operador licenciado, feed de odds, push notifications.
- Infra: containers, backups diários, logs centralizados, ambientes dev, homologação e produção separados.
11. Modelo de dados (resumo)
loja (id, cnpj, nome, fuso)produto (id, loja_id, sku, nome, preco, custo, estoque, estoque_min)venda e venda_item (status, pagamento, desconto, motivo_cancelamento)compra, despesa (categoria, valor, comprovante_url)usuario (id, perfil, kyc_status, idade_verificada)carteira e transacao (tipo, valor, status, idempotency_key)evento (esporte, data, status), odd (mercado, valor, vigente_ate)aposta e bilhete_item (stake, odd_no_momento, retorno_potencial, status)limite_jogo (tipo, valor, vigente_desde, autoexclusao_ate)auditoria (ator, acao, antes, depois, timestamp)
12. Riscos e mitigação
| Risco | Impacto | Mitigação |
|---|
| Operar apostas sem licença | Alto | Validação jurídica antes de qualquer lançamento; operar via operador licenciado |
| Menor de idade apostando | Alto | KYC e verificação de idade antes do depósito |
| Vazamento de dados financeiros | Alto | Criptografia, acesso mínimo, auditoria, testes de segurança |
| Odds erradas ou atrasadas | Alto | Aviso de mudança, bloqueio de aposta com odd vencida |
| Venda offline duplicada | Médio | Id único por venda e sincronização idempotente |
| Baixa adoção do lojista | Médio | Cadastro em 5 min, onboarding guiado, venda em 3 toques |
| Publicidade de apostas fora da regra | Médio | Revisão de peças com jurídico |
13. Marcos sugeridos
- Semana 0–1: validação jurídica e regulatória (apostas), escolha do operador/provedores, aprovação deste escopo.
- Semana 2–4: protótipo de telas (lojista e apostador), modelo de dados e API base.
- Semana 5–8: app Lojas v1 (venda, estoque, painel) e PWA com cadastro, KYC simulado e limites.
- Semana 9–10: integração de feed de odds, carteira e apostas, em ambiente de homologação com dados fictícios.
- Semana 11–12: testes de segurança, acessibilidade, piloto fechado com 3 lojas (fictícias para teste) e revisão jurídica final.
- Após o piloto: publicação nas lojas de apps e lançamento da PWA com operador licenciado.
Prazos são estimativas e dependem da equipe e da liberação jurídica.
14. Critérios de aceite (v1)
- Lojista registra venda, vê estoque baixar e o lucro líquido atualizar no painel, online e offline.
- Apostador não consegue apostar sem KYC e sem limites definidos.
- Aposta com odd vencida é recusada com mensagem clara.
- Autoexclusão bloqueia novas apostas imediatamente.
- Admin lança resultado com dupla confirmação e trilha de auditoria.
- PWA instala em Android e iOS e abre sem erro de console.
15. Perguntas em aberto para o dono
- A PWA será operada por você (com licença) ou por um operador parceiro?
- Qual provedor de odds e de KYC você prefere?
- Quais esportes entram na v1?
- Lojas: segmento (roupa, mercado, serviços)? Precisa de emissão de nota fiscal já na v1?
- Idiomas: só português?
16. Próximos passos
- Validação jurídica e regulatória das apostas.
- Aprovação deste escopo pelo dono.
- Protótipo navegável das duas jornadas principais.