SHOP.M3D.pro — documentação imersiva
Plataforma de lojas virtuais organizadas por áreas de interesse e grupos de usuários: uma rede de indicações vinculativas que conecta clientes e lojistas por comunidades temáticas — com impacto direto na promoção da saúde, na prevenção primária e no bem-estar psicossocial, ao reduzir isolamento, ruído digital e exposição ao consumo predatório.
🚀 Jornada do produto — do marco zero à expansão
Prévia ilustrada do roadmap: o que já foi entregue, o que está em obra e o que vem a seguir. Detalhes e critérios de aceite na seção 13.
App, API e banco estruturados; visão v0.01 documentada.
Convite → catálogo pessoal → carrinho multi-loja → PDF por lojista → WhatsApp.
Tradução PT/EN/ES com cache e seletor de idioma no app.
10 lojas-piloto em 1 área ativa; métricas de adoção e reputação.
Pagamento integrado, chat em tempo real e web completo.
Sumário — 22 seções
Estrutura institucional
Quem promove · como foi feitoLACibermedicina promove o ecossistema M3D.pro, e o SHOP.M3D.pro é a peça deste ecossistema dedicada ao consumo comunitário de confiança: lojas virtuais organizadas por áreas de interesse e grupos de usuários.
🧬 LACibermedicina
Iniciativa que reúne plataformas digitais de suporte à educação, documentação audiovisual e, agora, ao consumo comunitário de confiança. Onde o ecossistema já organiza o conhecimento clínico, o SHOP organiza o comércio entre pessoas que se conhecem e confiam — lojas reais apresentadas dentro de comunidades temáticas.
📦 Onde o projeto vive
A versão catálogo é desenvolvida pela organização LACibermedicina e publicada no repositório público da organização. O nome canônico do produto (shop.m3d) será definido pela governança do ecossistema — ver seção 21.
📐 Metodologia desta documentação
Documento único, standalone e autoexplicativo (CSS inline, zero dependências externas), que consolida as duas descrições oficiais do projeto e resolve as divergências explicitamente — sempre separando ✅ Realizado de 🎯 Planejado.
| Ponto | Descrição A | Descrição B | Resolução adotada |
|---|---|---|---|
| Versão | “Versão: catálogo” (sem número) | “Versão: catálogo (0.01)” | Adotada a versão 0.01 (nominal) |
| Funcionalidades de cliente | Convite, catálogo pessoal multi-loja, PDF split por lojista, idiomas PT/EN/ES, WhatsApp | Navegação por grupos, catálogos confiáveis, chat/vendedores, recomendações comunitárias, notificações | Consolidadas: núcleo da versão 0.01 + visão comunitária para fases seguintes |
| Funcionalidades de lojista | Vitrine, pedidos por cliente com edição real, convites, notificação | Métricas de engajamento, gestão de grupos, distribuição customizada | Núcleo 0.01 (editável) primeiro; métricas/gestão em fases posteriores |
| Data de referência | — | Setembro 2026 | Adotada, alinhada à atualização oficial do projeto |
🧭 Estado atual do projeto — setembro de 2026
O SHOP.M3D.pro está em estágio de fundação e MVP (versão 0.01): a base técnica existe e a visão está documentada; os próximos marcos — filtros por área, gestão de áreas, integração com a Cloud API do WhatsApp e beta institucional — estão planejados (seção 13).
🏗️ O que já está de pé
App multiplataforma (iOS · Android · Web) com identidade m3d.pro; catálogo por grupos de interesse com 6 áreas padrão; carrinho multi-loja com pedido dividido por lojista; pedidos com edição real e notificação ao cliente; conversa via WhatsApp.
🔨 O que está em construção
Filtros por área no catálogo pessoal e nos convites; gestão de áreas pelo master; polimento do redesign imersivo; automação de qualidade (lint, testes, build) e migração para a Cloud API do WhatsApp.
🗺️ O que vem depois
Tradução contextual completa PT/EN/ES com cache (M2), beta institucional com 10 lojas-piloto (M3) e expansão com pagamento, chat em tempo real e web completo (M4).
Por que este projeto toca saúde pública e preventiva
A motivação fora do códigoO SHOP.M3D.pro não é “só” um comércio: ele dialoga com três campos bem estabelecidos da saúde pública e age como recurso comunitário na promoção da saúde (Carta de Ottawa, 1986).
🌐 Determinantes sociais da saúde (DSS)
O consumo é um vetor de condições materiais e psicossociais que moldam saúde — renda, segurança alimentar, moradia, vínculos e suporte. Organizar o consumo por comunidades temáticas relaciona-se com a camada “redes sociais/comunidade” do modelo de Dahlgren & Whitehead.
🛡️ Prevenção primária
Reduzir exposição ao consumo predatório, à publicidade hiper-segmentada e ao ruído digital diminui estressores psicossociais documentados (ansiedade, comparação social, compras por impulso) — atuando antes do dano.
⚕️ Prevenção quaternária
Proteger pessoas de intervenções digitais desnecessárias e potencialmente iatrogênicas (spam, manipulação algorítmica, extração de dados) é exatamente o que a OMS-2018 chama de evitar o “excesso médico midiático” aplicado ao espaço informacional.
Seis pilares de impacto
🤝 Vínculo social
A indicação vinculativa recria o laço entre quem recomenda, quem compra e quem vende. Na literatura, redes comunitárias de suporte (peer support) aparecem como fator protetor em saúde mental e adesão terapêutica — o SHOP transplanta essa lógica para a esfera comercial.
🛡️ Redução do ruído
Estímulo irrelevante constante está associado a fadiga decisória, ansiedade e queda de bem-estar subjetivo. Ao restringir o acesso por convite a grupos de interesse, o app substitui a exposição por demanda pela exposição por necessidade real.
🛒 Consumo consciente
Carrinho dividido por loja + edição real do pedido + conversa direta via WhatsApp criam um circuito fechado de responsabilidade: o lojista responde pelo ajuste; o cliente revisa antes de finalizar. Reduz desperdício, devoluções e fricção administrativa.
🔒 Privacidade como princípio
Sem captura publicitária, o dado do usuário não vira produto — medida literal de prevenção quaternária digital: evita a iatrogenia informacional de ser alvo de inferências não consentidas.
🌎 Acesso centrado em comunidade
Grupos de interesse locais funcionam como o “suporte social” de Dahlgren & Whitehead — dimensão explicitamente ligada a melhores desfechos em saúde cardiovascular, saúde mental e mortalidade geral.
♻️ Economia local
A priorização de lojistas vinculados à comunidade discente/residencial/regional dialoga com evidências em economias locais: o capital circula dentro da rede, aumenta renda e emprego no próprio território, compondo a camada externa do DSS.
Esquema: Determinantes Sociais da Saúde
Dahlgren & WhiteheadO modelo de Göran Dahlgren e Margaret Whitehead (1991, reeditado em 2021) organiza os determinantes da saúde em camadas aninhadas — do núcleo individual aos fatores macroestruturais. O esquema abaixo mostra onde cada camada do SHOP.M3D.pro opera.
📌 Por que a camada 2?
É nela que moram os vínculos de confiança: família, amigos, vizinhos e grupos de interesse. O SHOP transforma essa camada em infraestrutura de comércio — a indicação substitui o algoritmo.
🔗 O aninhamento importa
Camadas externas (renda, ambiente, políticas) condicionam as internas. O SHOP não resolve a camada 5, mas fortalece a camada 2, que é o amortecedor entre o indivíduo e o macro.
🌱 Crescimento orgânico
A estrutura descentralizada e crescente de grupos temáticos reproduz o modo como comunidades reais se organizam — sem publicidade predatória.
Níveis de prevenção
Leavell & Clark → Pandve 2014 → Bae 2015A classificação de Leavell & Clark (1948), ampliada por Pandve (2014) e Bae (2015) para incluir primordial e quaternária, descreve cinco níveis de intervenção. O SHOP ocupa três zonas distintas — sem invadir a clínica.
🛡️ O que significa cada nível
Primordial — reduzir o surgimento cultural de fatores de risco (ambiente, valores, desigualdade). Primária — prevenir a exposição antes que cause dano. Secundária — detectar precocemente e reduzir prevalência. Terciária — reduzir complicações de doença instalada. Quaternária — proteger o usuário de intervenções desnecessárias ou iatrogênicas.
🚧 Limite operacional do SHOP
O produto nunca substitui cuidado clínico. Ele opera na camada informacional/comunitária que antecede (primária) ou evita (quaternária) o dano — a interface com profissionais de saúde deve ser preservada como prerrogativa do usuário.
Visão do produto e o problema
Essência · valores · escopo 0.01O SHOP.M3D.pro é um app mobile e web que funciona como uma rede de indicações baseada em grupos de interesse: consumidores chegam ao catálogo de um lojista por convite de alguém em quem confiam — e não por publicidade interceptada por algoritmos de ruído.
🤝 Relacionamento direto
Conexão próxima entre clientes e vendedores, baseada em confiança e no vínculo humano da indicação.
🎯 Grupos de interesse
Organização customizada que facilita o encontro de produtos relevantes, com menos busca e mais contexto.
🛡️ Proteção da privacidade
Reduz o impacto da publicidade predatória de redes e buscadores; o acesso é por convite, não por captura de dados.
💚 Saúde mental
Ambiente de consumo consciente, com menos ruído e mais relevância — comprar sem ansiedade algorítmica.
🔗 Indicações vinculativas
Recomendações orgânicas baseadas em comunidades: quem indica responde pela indicação, o que eleva a qualidade percebida.
🌐 Rede de confiança
Estrutura descentralizada e crescente de grupos temáticos, com crescimento orgânico sem publicidade predatória.
📢 O problema: consumo online distante e ruidoso
📢 Ruído predatório
Redes e buscadores monetizam atenção: o consumidor é bombardeado por anúncios não solicitados e o lojista paga caro para ser empurrado no feed — sem vínculo e sem fidelidade.
🧊 Distanciamento
O consumo tradicional online separa comprador e vendedor: sem diálogo, sem confiança, sem contexto. O resultado é desconfiança mútua e disputa por preço.
🧩 Fragmentação
Produtos relevantes ficam perdidos em catálogos gigantes. Quem busca nichos (artesanato, saúde, educação, itens regionais) não encontra — e quem vende nichos não é encontrado.
🔄 A resposta do SHOP.M3D.pro — quatro trocas de modelo
🎯 Escopo da versão catálogo (MVP 0.01)
Objetivo: provar de ponta a ponta o ciclo de confiança convite → catálogo pessoal multi-loja → carrinho dividido por lojista → PDF + link do pedido → conversa direta (WhatsApp), com RBAC de 4 níveis ativo e tradução contextual demonstrativa.
✅ Dentro do escopo 0.01
- Convites por link, QR e e-mail com token de acesso
- Catálogo pessoal multi-loja com filtros por loja e categoria
- Relatório em PDF do catálogo/compra filtrado
- Carrinho que separa itens por lojista; 1 PDF por lojista + link do pedido
- Pedidos por cliente com edição real (quantidade, preço, disponibilidade, status)
- Notificação do cliente ao ajustar o pedido
- WhatsApp click-to-chat · Hierarquia master/admin/lojista/cliente
- Idiomas PT/EN/ES com tradução contextual por IA (demonstrativa)
⏭️ Fora do escopo 0.01 (roadmap)
- Sistema de pagamento integrado
- Chat em tempo real dentro do app
- Sistema de avaliações e reputação
- Métricas avançadas de engajamento por lojista
- Integração ampla com múltiplos vendedores externos
- Expansão web completa (a web inicial acompanha o app via React Native Web)
Públicos, personas e RBAC de 4 níveis
Quem pode o quêHierarquia de acesso validada no backend (nunca apenas na interface). O convite é a porta de entrada; o RBAC é a fronteira invisível de cada perfil.
| Perfil | Acesso | Abrangência |
|---|---|---|
| master | Controle total | Clientes, lojistas e administradores — gestão global, grupos e parâmetros |
| admin | Gerencia apenas os lojistas vinculados a ele | Seu conjunto de lojas; sem acessar áreas fora do domínio |
| lojista | Apenas a sua loja | Vitrine, produtos, pedidos, convites |
| cliente | Acesso somente por convite | Catálogos convidados, carrinho multi-loja, pedidos próprios |
🛍️ Persona — Cliente
Recebe um convite (link/QR/e-mail) de um lojista ou de alguém de sua comunidade. Navega catálogos por grupos de interesse, monta um carrinho que reúne produtos de várias lojas, recebe um pedido organizado por lojista e conversa direto pelo WhatsApp.
🏪 Persona — Lojista
Mantém uma vitrine própria, convida seus clientes, recebe pedidos separados por cliente e edita o pedido de verdade: quantidade, preço, disponibilidade e status — com notificação automática ao cliente a cada ajuste.
🧭 Matriz funcional × perfil
| Funcionalidade | cliente | lojista | admin | master |
|---|---|---|---|---|
| Navegar catálogos por convite | ✓ | ✓ (o próprio) | — | ✓ |
| CRUD de produtos / vitrine | — | ✓ (sua loja) | — | ✓ |
| Carrinho multi-loja + PDF split | ✓ | — | — | ✓ |
| Editar pedido (qtd, preço, disp., status) | — | ✓ | ✓ (sua rede) | ✓ |
| Gerar convites | — | ✓ | ✓ | ✓ |
| Gerir grupos de interesse | — | — | ✓ | ✓ |
| WhatsApp click-to-chat | ✓ | ✓ | — | ✓ |
| Tradução contextual PT/EN/ES | ✓ | ✓ | ✓ | ✓ |
Áreas de interesse — 6 padrão no backend
Áreas padrão do produtoQuando o master/administrador cria uma loja sem informar áreas, o sistema atribui as 6 áreas padrão já criadas em disco (estado verificado em 2026-09-04):
📲 Como aparecem no app
O home do cliente exibe uma faixa “Áreas de interesse” com chips coloridos (um ícone por área) que filtra a lista de lojas pela área selecionada via ?group_id=. No formulário da loja (admin/master), há multi-seleção de áreas e botão “+ criar nova área” na hora — o catálogo não é fechado: cresce com a comunidade.
🧱 Decisão arquitetural validada
As áreas funcionam como TAXA — não como única dimensão — garantindo que categorias futuras (ex.: “Saúde & Bem-estar”, “Educação”) sejam criadas pelo master sem mudança de schema.
Arquitetura técnica
Stack técnicaA arquitetura separa de forma clara o front-end em Expo Router (file-based) — com telas imersivas em headers gradientes — do back-end em FastAPI e da base de dados MongoDB.
| Camada | Tecnologia | Responsabilidade |
|---|---|---|
| Frontend (mobile + web) | Expo + React Native (Expo Router, file-based routing) | App multiplataforma iOS/Android + versão web (react-native-web / expo start --web); navegação por arquivos; telas de catálogo, carrinho, pedidos e convites |
| Backend (API) | FastAPI (Python) | REST/JSON: autenticação, RBAC, catálogo, carrinho, pedidos, convites, geração de PDF, notificações |
| Banco de dados | MongoDB | Persistência documental: usuários, grupos, lojas, produtos, carrinhos, pedidos, convites, cache de tradução, auditoria |
| IA | Tradução contextual (Emergent LLM / Gemini) | Tradução PT/EN/ES com cache; serviço isolado do domínio para não acoplar a API |
| Comunicação | WhatsApp click-to-chat (wa.me) | Link direto cliente ↔ lojista, sem necessidade de API paga na versão 0.01 |
| Engine de geração server-side (ex. ReportLab / WeasyPrint) | Relatórios do catálogo e pedido dividido por lojista, gerados sob demanda | |
| Infra | Docker · Integração contínua · EAS Build | Ambientes, CI/CD, build do app e deploy da API |
Modelo de dados
Coleções MongoDBDuas visões complementares: o que já é confirmado no código (✅) e o que é proposta documental 💡 como ponto de partida para as especificações técnicas documentadas do produto.
✅ Estrutura presente no núcleo v0.01
| Coleção | Status | Função |
|---|---|---|
| users | ✅ confirmada | Perfis master · admin · lojista · cliente, com acento dourado do master — identidade, idioma, role, status |
| stores | ✅ confirmada | CRUD ativo; campo group_ids (multi-área) — lojas/vitrines com áreas vinculadas |
| products | ✅ confirmada | Pedidos por cliente e edição real — itens do catálogo: quantidade, preço, disponibilidade, status |
| orders | ✅ confirmada | Tela imersiva com header gradiente — pedidos por cliente, histórico de edições, notificação |
| groups | ✅ confirmada | Endpoint /groups; 6 áreas padrão criadas — áreas de interesse com filtro ?group_id= |
| invitations | ⏳ em consolidação | Token com expiração e escopo RBAC (link / QR / e-mail) — descrita na visão oficial |
| translations_cache | ⏳ em consolidação | Cache de tradução contextual PT/EN/ES (seletor de idioma no app) |
| audit_logs | 🎯 planejada | Trilha para LGPD e governança clínica (edição de pedido exige rastreio) |
⚠️ O que está marcado como em consolidação é projetado a partir da visão oficial do produto — confirme na base de código antes de citar como contrato público de API.
💡 Proposta documental de coleções (ponto de partida)
| Coleção | Propósito | Campos principais (resumo) |
|---|---|---|
| users | Contas de todos os perfis | nome, email, telefone, idioma, role (master/admin/lojista/cliente), status, timestamps |
| groups | Áreas de interesse e comunidades temáticas | nome, slug, descrição, idiomas, owner (admin/master), visibilidade |
| group_members | Vínculo usuário ↔ grupo ↔ papel | userId, groupId, roleNoGrupo, conviteId, dataEntrada |
| stores | Lojas / vitrines dos lojistas | proprietarioId (lojista), nome, logo, descrição, categoria, grupoId, WhatsApp, status |
| products | Itens do catálogo | lojaId, nome, descrição, preço, disponibilidade, categoria, imagens, variantes |
| carts / cart_items | Carrinho pessoal multi-loja | clienteId, itens[{lojaId, productId, qtd}], valorTotal |
| orders / order_items | Pedido por cliente, agrupado por loja | clienteId, lojaId, itens, quantidades, preços, disponibilidade, status, histórico de edições |
| invitations | Convites (link / QR / e-mail) | tipo, token, emissorId, lojaId/grupoId, destino (email/telefone), expiração, status |
| translations_cache | Cache da tradução contextual | chave (texto+idioma origem/destino), resultado, modelo IA, timestamp |
| audit_logs | Trilha de auditoria | atorId, ação, entidade, antes/depois, IP, timestamp |
Fluxos de ponta a ponta
O comportamento-âncora do produto① Convite (link · QR · e-mail)
- Emissão — Lojista (ou admin) gera convite com token único, escopo e expiração
- Entrega — Link, QR ou e-mail enviados ao cliente
- Abertura — Cliente abre o link / lê o QR no app
- Validação — Backend valida token, expiração e escopo (RBAC)
- Acesso — Perfil cliente criado/vínculo ativado → catálogo liberado
② Carrinho multi-loja → PDF por lojista + link do pedido
O comportamento-âncora do produto: o mesmo carrinho quebra por lojista, e cada um recebe só os seus itens.
- Catálogo — Cliente navega por grupos e lojas convidadas
- Filtros — Filtra por loja e categoria; monta catálogo pessoal
- Carrinho — Itens de várias lojas no mesmo carrinho
- Geração — Backend agrupa por lojista e gera 1 PDF por lojista com apenas os itens dele + link do pedido
- Conversa — Cliente envia PDF e link ao lojista via WhatsApp click-to-chat
③ Edição real do pedido com notificação ao cliente
- Recebimento — Lojista vê pedidos por cliente, separados por loja
- Edição — Quantidade, preço, disponibilidade ou status
- Registro — Histórico + trilha de auditoria
- Notificação — Cliente avisado do ajuste no app
- Confirmação — Cliente revisa e apresenta contraproposta via WhatsApp
Segurança, privacidade e LGPD
Exigível já em 2026🔐 Controle de acesso
- RBAC de 4 níveis validado no backend (não só na interface)
- Tokens de convite com expiração e escopo por loja/grupo
- JWT para autenticação do app
- Trilha de auditoria (
audit_logs) para edições sensíveis - Webhook WhatsApp pré-configurado para a Cloud API (credenciais protegidas no ambiente)
🛡️ LGPD — o que é exigível já em 2026
- Minimização: só dados necessários ao convite e ao pedido (nome, e-mail, telefone, idioma)
- Consentimento: aceite no convite, com registro de data/hora
- Criptografia: TLS em trânsito + dados pessoais protegidos em repouso
- Direitos do titular: portabilidade, correção, exclusão via master
- Política de retenção explícita por tipo de dado
- DPO: shop@m3d.pro (atualmente o contato geral do projeto)
- Princípio de produto: sem captura publicitária — diferencial de proteção quaternária digital
Ambientes, CI/CD e qualidade
Automação e qualidadeA automação de qualidade (lint, testes, build) está em consolidação e deve ser formalizada em um pipeline de integração contínua antes do beta — o desenvolvimento combina curadoria humana e automação assistida.
| Ambiente | Estado atual | Próximo passo |
|---|---|---|
| Local | Serviços rodando com dados de teste | Padronizar instruções de setup |
| staging | Ambiente de validação em preparação | URL pública a documentar |
| production | Meta Cloud API pendente de migração do número | Migrar +55 11 92094-6954 para CLOUD_API no painel Meta |
| CI/CD | Em consolidação | Adicionar pipeline de integração contínua: lint · testes · EAS Build · deploy API |
| Webhook WhatsApp | Configurado em /api/webhooks/whatsapp | Esperar migração para validar fluxo incoming |
Roadmap: realizado × planejado
Da fundação à expansãoComo o roadmap se desenrola: 5 fases em sequência, da fundação à expansão — cada uma com entregas e critério de aceite. As barras de status mostram o ponto em que o produto está hoje.
🏗️ Fase 0 · Fundação
semanas 1–2
Base do projeto estruturada: app, API e banco conversando; visão oficial documentada; automação de qualidade inicial.
Critério: app rodando em iOS, Android e Web, com pipeline verde.
🛒 Fase 1 · MVP catálogo
semanas 3–6
Autenticação e RBAC · convites por link/QR/e-mail · vitrine e produtos · catálogo pessoal com filtros · carrinho multi-loja · PDF por lojista · pedidos com edição real · WhatsApp.
Critério: cenário convite → catálogo → carrinho → PDF → WhatsApp aceito de ponta a ponta em staging.
🌐 Fase 2 · IA contextual
semanas 7–8
Tradução PT/EN/ES por IA com cache · seletor de idioma no app · strings de produto e catálogo traduzidas em contexto.
Critério: navegação completa em 3 idiomas.
🏘️ Fase 3 · Comunidade
semanas 9–11
Gestão de grupos por admin/master · métricas de engajamento por lojista · avaliações e reputação · notificações push de pedidos e ajustes.
Critério: admin cria grupo, lojista vê métricas mensais, cliente avalia pedido concluído.
🚀 Fase 4 · Expansão
semanas 12+
Pagamento integrado · chat em tempo real · integração ampla multi-vendedores · web completo · integrações externas (logística, ERP leve).
Critério: pedido pago de ponta a ponta; 10+ lojas ativas em um grupo piloto.
✅ Realizado — base atual do produto
?group_id= no servidor🎯 Planejado (próximos marcos propostos)
Playbook de ritos e metodologia
Como o time entregaO playbook é o código de conduta de entrega do projeto: como o time se organiza, o que significa “pronto” e quais ritos sustentam a cadência.
🗓️ Ritmo de trabalho do time
O desenvolvimento combina a curadoria do mantenedor com automação assistida, o que gera cadência de entregas frequentes — mais próxima de releases contínuos do que de sprints quinzenais clássicas. Recomenda-se formalizar:
🔁 Ritos sugeridos 💡
- Daily curta de 15 min: revisão do funnel, áreas pendentes, bugs
- Revisão semanal com stakeholders do ecossistema M3D.pro
- Review/demo ao final de cada sprint; retrospectiva a cada milestone
- histórico de versões versionado: criar tags semânticas (v0.01, v0.02, …) para citar versões
✔️ Definition of Done
Um item só está pronto quando: código revisado · testes passando no CI · documentado em docs/ · deployado em staging · cenário E2E do MVP aceito.
📂 Organização do código (proposta)
| Pasta | Conteúdo |
|---|---|
| Frontend (app) | Expo + React Native (Expo Router, file-based): (auth)/ login e aceite de convite · (cliente)/ catálogo, carrinho, pedidos · (lojista)/ vitrine, produtos, pedidos · (admin)/ gestão de lojistas e grupos |
| Backend | FastAPI: api/ rotas (auth, catalogo, pedidos, convites, pdf, notificacoes) · core/ config, segurança, RBAC, auditoria · services/ ia_tradução, pdf, whatsapp · models/ esquemas MongoDB |
| Documentação | Guias e especificações do produto (ver seção 21) |
| Automação de qualidade | Integração contínua: lint · testes · build · deploy (S0) |
| Visão oficial | Documento de abertura do produto |
Sprints sugeridas
Dois horizontes de planejamentoOs anexos trazem duas leituras complementares do mesmo ciclo. A curta (v0.01 → v0.02) destrava os próximos marcos verificados; a longa (até o beta institucional) é a sequência de 12 sprints de fôlego.
📋 Horizonte curto — ciclo v0.01 → v0.02 (recomendado, 1 semana por sprint)
| Sprint | Foco | Entregas-chave |
|---|---|---|
| S0 | Fundador | Licença · CI básico · Histórico de versões · Documentação inicial |
| S1 | Filtro estendido | Catálogo pessoal filtrado por área · convite escolhe área |
| S2 | Gestão de áreas | Tela master: criar · renomear · trocar cor · ícone · excluir |
| S3 | Redesign da loja | Vitrine com logo · áreas em destaque · i18n aplicado a 100% das strings |
| S4 | WhatsApp Cloud API | Migração do número · validação do webhook · envio automático de PDF + link |
| S5 | Beta institucional | 10 lojas-piloto · 1 área ativa · métricas de adoção · ajustes finos |
| S6 | Reputação inicial | Avaliação do pedido concluído · comentários públicos moderados |
🗺️ Horizonte longo — sequência até o beta (proposta desta documentação)
| Sprint | Foco | Principais entregas |
|---|---|---|
| S0 | Fundador | Repo, CI, boilerplate Expo Router + FastAPI + MongoDB, docs baseline |
| S1 | Identidade | Autenticação JWT, RBAC 4 níveis, cadastro por convite |
| S2 | Convites | Link / QR / e-mail, tokens com expiração e escopo |
| S3 | Catálogo | Vitrine, CRUD de produtos, filtros por loja/categoria |
| S4 | Carrinho | Carrinho multi-loja, catálogo pessoal, PDF do relatório |
| S5 | PDF split | Agrupamento por lojista, 1 PDF por lojista + link do pedido |
| S6 | Pedidos | Pedidos por cliente, edição real, histórico e notificação |
| S7 | Comunicação | WhatsApp click-to-chat, UX multi-loja, polimento |
| S8 | IA | Tradução contextual PT/EN/ES, cache, seletor de idioma |
| S9 | Comunidade | Gestão de grupos (admin/master), métricas do lojista |
| S10 | Reputação | Avaliações, notificações push, ajustes finos |
| S11 | Hardening | LGPD, auditoria, testes E2E completos, beta institucional |
Estimativa de 12 sprints (~6 meses) para a fase beta, considerando 1–2 desenvolvedores. As descrições oficiais do projeto não publicam cronograma ou créditos — esta sequência é elaboração desta documentação e está marcada como 💡 proposta.
Passos de implementação — guia prático
Do estado atual ao betaOito passos em ordem de execução, derivados diretamente do estado verificado do repositório e dos marcos planejados. Cada passo indica por que existe, como executar e quando está pronto.
- P0 · Base transparente — Explicitar na visão oficial o estágio atual (fundação e MVP em construção), separando o que já foi entregue do que está planejado (seção 13). Por quê: o alinhamento entre narrativa e maturidade é o principal fator de credibilidade. Pronto quando: a documentação oficial diz claramente o que existe e o que vem a seguir.
- P1 · Fundação legal — Definir e publicar a licença de uso do código (ex.: MIT) e um histórico de versões (histórico de versões). Por quê: sem licença formal, o reuso e a colaboração ficam juridicamente frágeis. Pronto quando: a licença está documentada e o histórico de versões registra a v0.01.
- P2 · Quality gate — Estruturar o pipeline de integração contínua com lint + testes (Jest para React Native, pytest para FastAPI). Por quê: a qualidade não pode depender apenas de revisão manual. Pronto quando: pipeline verde a cada integração.
- P3 · Documentação oficial — Publicar a documentação estruturada: arquitetura, guias de usuário e lojista, especificações técnicas, roadmap, playbook e registro de decisões — ver seção 21. Por quê: onboarding de novos colaboradores e stakeholders. Pronto quando: os documentos oficiais estão publicados e acessíveis.
- P4 · Filtro por área estendido (S1) — Levar o filtro
?group_id=ao Catálogo pessoal e ao convite (lojista escolhe área ao convidar). Por quê: é o próximo marco funcional com maior valor percebido. Pronto quando: cliente filtra catálogo pessoal por área e recebe convite já segmentado. - P5 · Gestão de áreas no master (S2) — Tela dedicada: criar, renomear, cor, ícone, excluir. Por quê: o catálogo cresce com a comunidade, mas hoje quem cria área precisa do backend. Pronto quando: master cria uma área nova sem tocar em código.
- P6 · WhatsApp Cloud API (S4) — Migrar +55 11 92094-6954 para CLOUD_API no painel Meta e validar o webhook
/api/webhooks/whatsapp. Por quê: destrava o envio automático de PDF + link (dependência externa manual). Pronto quando: mensagens incoming chegam aos logs e o PDF é entregue automaticamente. - P7 · Beta institucional (S5) — Onboarding de 10 lojas-piloto em 1 área ativa, com métricas de adoção (funil convite → 1º pedido). Por quê: validação com casos reais; o cold start do convite exige comunidade inicial. Pronto quando: 10 lojas ativas com pedidos reais e funil ≥ 30%.
- P8 · Loop de medição — Alimentar os KPIs da seção 19 a cada sprint: releases, funil, tempo de PDF, cobertura i18n, CI verde. Por quê: metas honestas substituem números inflados. Pronto quando: painel simples de métricas consultável pelo master.
Estratégias de monetização
💡 Elaboração desta documentação🏪 Plano Lojista (freemium)
Vitrine, convites e pedidos gratuitos. Planos pagos desbloqueiam: edição avançada de pedidos em lote, estatísticas de conversão, destaque da loja dentro do grupo e múltiplos idiomas de catálogo com revisão.
plan em stores; limite de produtos/convites no plano free; gateway de assinatura em fase futura (fora do 0.01).🤝 Taxa por transação (opcional)
Quando o sistema de pagamento integrado entrar (roadmap Fase 4), cobrar taxa reduzida sobre pedidos concluídos dentro do app — com teto por faixa de valor, para proteger a comunidade.
🏘️ Licenciamento institucional
Vender a instalação do ecossistema para universidades, cooperativas, condomínios, associações de bairro e programas de extensão: uma “ilha de confiança” com marca própria sobre a mesma base.
📈 Destaque comunitário (impulso ético)
Em vez de leilão de anúncios, impulso editorial visível: lojista paga para aparecer em “lojas em destaque” dentro da sua área, com selo transparente “promovido pela comunidade”.
🇧🇷 Serviços de valor agregado
Tradução PT/EN/ES avançada com glossário próprio do ecossistema, certificação “loja verificada” após revisão editorial e relatórios de sustentabilidade local (impacto de renda circulante).
🔁 Rede de indicação B2B
Comunidades-mãe (ex.: polo acadêmico, clube, paróquia) pagam um plano de administração comunitária que dá dashboard de membros, moderação e estatísticas de consumo do grupo.
admin já existe — derivar o plano pela quantidade de lojistas vinculados.| Fluxo de receita (proposta) | Quem paga | Fase | Princípio protegido |
|---|---|---|---|
| Plano Lojista (assinatura mensal/anual) | Lojista | Pós-beta | Vitrine básica e convites seguem gratuitos |
| Taxa sobre pagamento in-app (opcional) | Lojista (descontada no pedido) | Fase 4 (pagamento) | Fluxo WhatsApp gratuito permanece |
| Licenciamento institucional/white-label | Instituições | Pós-beta | Governança local preservada |
| Impulso comunitário (badge visível) | Lojista | Pós-beta | Nunca se disfarça de recomendação orgânica |
| Add-ons (tradução avançada, verificação, relatórios) | Lojista / comunidade | Pós-beta | Revisão editorial obrigatória |
| Plano de administração comunitária | Comunidade-mãe | Fase 3+ | RBAC por domínio mantido |
Integração com o ecossistema M3D.pro
Uma peça de um todo maiorO SHOP.M3D.pro não é um app isolado: é o componente de consumo comunitário de confiança do ecossistema M3D.pro da LACibermedicina, que já organiza educação e documentação audiovisual do conhecimento clínico. Onde o ecossistema estrutura o conhecer, o SHOP estrutura o consumir com quem se confia.
⚖️ Governança clínica compartilhada
Regras do ecossistema aplicadas ao SHOP
- O produto é informacional; nunca substitui avaliação clínica
- Toda comunidade preserva a prerrogativa do usuário de buscar cuidado profissional
- Lojistas não podem usar o canal para discurso anti-científico (em especial vacinal)
- Conteúdos que envolvem saúde seguem revisão editorial antes de qualquer selo de “revisão clínica”
- Dados clínicos (integrações futuras) seguem trilha de auditoria + consentimento granular
Efeito de rede para todo o hub
As fases 1 e 2 (MVP + IA) desbloqueiam o Beta institucional; a Fase 3 conecta o SHOP às comunidades temáticas do M3D.pro, reforçando o efeito de rede de todo o ecossistema: quem aprende no M3D.pro encontra, por indicação de confiança, quem vende perto — e vice-versa. O contato oficial unificado é shop@m3d.pro.
KPIs e critérios de sucesso
Baseline verificado vs metas honestas📊 Ponto de partida atual (setembro de 2026)
🎯 Metas para o próximo ciclo (v0.02, sprints S0–S6)
| Métrica | Baseline | Meta v0.02 | Como medir |
|---|---|---|---|
| Versão pública | v0.01 interna | v0.02 lançada com licença e documentação | histórico de versões + docs publicados |
| Filtros por área | apenas no home | catálogo pessoal + convites | Uso no produto (sprint S1) |
| Lojas-piloto | 0 publicada | ≥ 10 lojas em área-piloto até o fim da S5 | Contagem via master dashboard |
| Convites aceitos → 1º pedido | não medido | ≥ 30% | Funil do backend |
| Geração de PDF | não medida | < 3 s p95 | Logs do engine PDF |
| Cobertura i18n | parcial (login + perfil) | 100% das strings em PT/EN/ES | Auditoria por sprint |
| WhatsApp Cloud API | número em SMB/OnPremise | migrado e validado | Painel Meta (ação manual) |
| CI verde | automação em consolidação | lint + testes + build verde | Pipeline de integração contínua |
| Webhooks WhatsApp | configurados, não validados | mensagens incoming chegando | Logs do endpoint |
| Documentação | visão oficial + este documento | 7 documentos oficiais publicados | Acessíveis no material do projeto |
🧭 Quadro de indicadores por dimensão (proposta)
| Dimensão | Indicadores |
|---|---|
| Produto | DAU/WAU · pedidos por loja/mês · tempo de ciclo convite → pedido · % de pedidos editados sem erro |
| IA e busca | Latência de tradução em cache e sem cache · % de strings cobertas em PT/EN/ES |
| Confiança | NPS · taxa de recompra · avaliações positivas · ticket médio por comunidade |
| Compliance | 0 incidentes de dados · % de usuários com consentimento registrado |
| Operação | Uptime da API · tempo médio de geração de PDF · backup restaurado com sucesso |
Riscos, dependências e mitigação
Visão executivaRiscos consolidados das duas descrições oficiais, com impacto e mitigação concreta. Os quatro primeiros são verificados no repositório; os demais são riscos operacionais de projeto.
| Risco | Impacto | Mitigação |
|---|---|---|
| Licença de uso do código ainda não formalizada | Risco jurídico e de colaboração | Formalizar a licença na S0 antes de qualquer divulgação |
| Integração contínua em consolidação | Qualidade pode depender só de revisão manual | Estruturar pipeline de lint + testes na S0 |
| WhatsApp ainda em SMB (não Cloud API) | Envio automático bloqueado; só links wa.me | Migrar +55 11 92094-6954 por ação manual na Meta |
| Cobertura i18n parcial | Experiência inconsistente em EN/ES | Auditoria de chaves · traduções por IA como rascunho + revisão |
| Projeto jovem — estágio inicial de maturidade | Baixa confiança de colaboradores externos | Entregas versionadas · comunicação pública transparente |
| Lojas-piloto ainda não publicadas | Beta institucional sem casos reais | Onboarding focado na S5 · 10 lojas vinculadas a 1 área ativa |
| Dependência crítica da IA de tradução | Indisponibilidade afeta usabilidade | Cache de tradução + degradação graciosa (volta ao PT) |
| Alinhamento entre documentação e produto | Promessas podem não casar com a maturidade | Este playbook separa explicitamente “realizado vs planejado” |
| Adoção depende do convite (cold start) | Crescimento lento sem comunidade inicial | Lançar com admin-piloto conhecido + grupos universitários/clubes |
| Variáveis sensíveis no ambiente | Exposição de chaves Meta se vazar no front | Backend-only para chamadas Meta; revisar que não haja segredos no código versionado |
| Qualidade semântica da tradução por IA | Termos mal traduzidos afetam a confiança | Cache revisável, glossário do ecossistema, fallback para PT |
| Divergência de escopo admin/master | Fronteiras de acesso mal entendidas | RBAC testado por cenário; matriz da seção 06 como contrato; testes de autorização automatizados |
| Operação de PDF (acentos, variantes) | Relatórios inválidos em PT/EN/ES | Engine testado para UTF-8 e 3 idiomas; teste E2E do PDF no CI |
Material do projeto e documentação
Onde encontrarO produto é desenvolvido pela LACibermedicina no âmbito do ecossistema M3D.pro. O código e a documentação ficam hospedados no repositório público da organização; o endereço canônico do produto (shop.m3d) será definido pela governança do ecossistema.
📄 Onde vive o código
Repositório público da organização LACibermedicina — aberto para leitura e colaboração; a autenticidade das versões é garantida por entregas versionadas.
📚 Documentação oficial
Arquitetura · Guia do usuário · Guia do lojista · Especificações técnicas · Roadmap · Playbook · Registro de decisões — com base nas seções deste documento.
📬 Canal oficial
Dúvidas, parcerias e feedback do ecossistema: shop@m3d.pro.
| Documento oficial | Conteúdo (base nesta documentação) | Status |
|---|---|---|
| Arquitetura | Camadas, decisões de stack e integrações (seção 08) | a publicar |
| Guia do usuário | Convite, catálogo, carrinho, PDF e WhatsApp | a publicar |
| Guia do lojista | Vitrine, produtos, pedidos e edição real | a publicar |
| Especificações técnicas | Modelo de dados, endpoints, RBAC e LGPD (seções 09–11) | a publicar |
| Roadmap | Marcos e critérios de aceite (seção 13) | a publicar |
| Playbook | Ritos, sprints e Definition of Done (seções 14–15) | a publicar |
| Registro de decisões | Divergências resolvidas (seção 01) e decisões futuras | a publicar |
Referências acadêmicas e técnicas
Fundamentação📚 Saúde pública e DSS
| Referência | Link |
|---|---|
| Dahlgren G, Whitehead M. The Dahlgren-Whitehead model of health determinants: 30 years on and still chasing rainbows. Public Health, 2021. | ScienceDirect · PDF |
| Dahlgren G, Whitehead M. European strategies for tackling social inequities in health. WHO Europe, 2006. | PDF (Fiocruz) |
| Carvalho ML et al. Suicide in the elderly: approach to social determinants of health. Rev Bras Enferm, 2020. | SciELO PDF |
| Jahnel T et al. The digital rainbow: digital determinants of health inequities. Digital Health, 2022. | SAGE PDF |
| WHO. Diretrizes sobre política de saúde e apoio sistémico para Agentes Comunitários de Saúde, 2018. | PDF (WHO IRIS, PT) |
| OMS. Serviços de saúde mental focados no apoio de pares. | Referência |
🛡️ Níveis de prevenção e promoção da saúde
| Referência | Link |
|---|---|
| Pandve HT. Changing concept of disease prevention: From primordial to quaternary. Arch Med Health Sci, 2014. | LWW |
| Bae JM. Implementation of quaternary prevention in the Korean healthcare system. J Prev Med Public Health, 2015. | PMC |
| Ishizumi A et al. Beyond misinformation: developing a public health prevention framework for managing information ecosystems. Lancet Public Health, 2024. | The Lancet |
| Tesser CD et al. A conceptual framework for good preventive practices. 2024. | PMC 11405023 |
| Moraes CF et al. Prevenção em saúde na prática médica: da primária à quaternária. 2015. | Dialnet PDF |
⚖️ LGPD, e-commerce e violência patrimonial
| Referência | Link |
|---|---|
| Santos TAC. A LGPD e o comércio eletrônico. REASE, 2026. | REASE |
| Costa RRDEJ. Evolução dos direitos do consumidor no e-commerce brasileiro. 2025. | |
| FGV. Maioria dos marketplaces ignora exigências da LGPD. O Globo, 2025-04-29. | O Globo |
| Plutarco RSA. Compras Online e Vulnerabilidade Psicológica. RCMOS, 2025. | RCMOS |
| Quirino AH. Violência patrimonial: uma revisão integrativa. RBSP, 2026. | PDF (Fórum Segurança) |
🛠️ Stack técnica — referências 2026
| Referência | Link |
|---|---|
| Expo Router · core concepts | docs.expo.dev |
| Agilesoftlabs. Expo Router in 2026: file-based navigation | agilesoftlabs.com |
| Bacon E. RFC: file-based routing in React Native | evanbacon.dev |