Referência de aplicação. Esta é uma arquitetura ilustrativa e uma lista de verificação de escopo, não um projeto de cliente verificado nem uma implantação medida. As tecnologias, o escopo de integração e os itens de entrega são acordados para o briefing real.
Cenário e restrições
Uma marca de varejo que vende por meio de um mini programa do WeChat e também opera lojas físicas. O requisito essencial é que o estoque permaneça correto entre os canais durante as promoções: estoques de canal atualizados de forma independente podem criar risco de venda excedente, a menos que as regras de reserva, sincronização e reconciliação sejam definidas. Os pontos de associação e os cupons também devem ser liquidados de forma consistente, pois um desconto aplicado duas vezes representa uma perda financeira direta.
Arquitetura
Camadas e responsabilidades
| Camada | Tecnologia | Responsabilidade |
|---|---|---|
| Cliente | UniApp (WeChat + Douyin a partir de uma única base de código) | Navegação pelo catálogo, carrinho, checkout, central do membro. Nenhuma regra de negócio é considerada confiável aqui; o cliente apenas renderiza o estado confirmado pelo servidor. |
| API | Go + Gin, sem estado atrás de um balanceador de carga | Validação de solicitações, autenticação, regras de negócio e limites de transação. Escalável horizontalmente porque nenhum estado de sessão permanece no processo. |
| Cache | Redis | Dados quentes do catálogo, contadores de estoque para vendas relâmpago, bloqueios distribuídos e chaves de idempotência para callbacks de pagamento. |
| Armazenamento | MySQL com réplica de leitura | Dados autoritativos. As gravações vão para o primário; as leituras do catálogo e dos relatórios podem ser encaminhadas para uma réplica quando a carga de leitura justificar isso. |
| Administração | Vue 3 + Element Plus | Gerenciamento de catálogo, pedidos, estoque, promoções e lojas, com permissões impostas pelo back-end. |
| Assíncrono | Workers de fila | Reconciliação de pagamentos, envio de mensagens, agregação de relatórios e liberação de estoque após o timeout do pedido — qualquer tarefa que não deve bloquear a solicitação de checkout. |
Modelo de dados
As tabelas abaixo contêm as regras das quais todo o restante depende. Erros aqui são o que transformam uma demonstração funcional em um sistema que não pode ser ampliado.
Entidades principais
| Entidade | Campos principais, relações e regras |
|---|---|
| produto / sku | Um produto corresponde a vários SKUs por combinação de atributos. O preço e o estoque pertencem ao SKU, nunca ao produto; caso contrário, a precificação de múltiplas variantes se torna impossível de ampliar. |
| estoque | Linhas identificadas por (sku_id, location_id), contendo on_hand e reserved. O estoque disponível é derivado como on_hand menos reserved; as transações e a reconciliação ainda precisam ser testadas para detectar discrepâncias. |
| inventory_txn | Livro-razão com registros apenas adicionados, contendo cada movimentação de estoque, código de motivo e pedido de origem. O estoque atual deve sempre ser reproduzível pela reaplicação deste livro-razão — isso torna as discrepâncias auditáveis em vez de discutíveis. |
| pedido / order_item | O pedido contém a máquina de estados e os totais; os itens registram o título, a especificação e o preço unitário do SKU no momento da compra, para que futuras edições do catálogo não possam reescrever o histórico do pedido. |
| payment_txn | ID da transação do gateway, valor, status e payload bruto do callback. Exclusivo no ID do gateway, para que um callback repetido do WeChat Pay não possa ser aplicado duas vezes. |
| membro / point_txn / cupom | O saldo e os pontos do membro são derivados de um registro de transações com entradas apenas adicionadas. As linhas de cupons contêm escopo, limite, prioridade de acúmulo e um registro used_at usado para impor o uso único. |
Interfaces principais
Endpoints que carregam as regras de negócio
| Endpoint | Finalidade e observações sobre concorrência |
|---|---|
| POST /api/v1/orders | Cria o pedido e reserva o estoque dentro de uma única transação de banco de dados. Sob carga de venda relâmpago, a reserva passa primeiro por uma operação atômica de decremento no Redis, com o MySQL como registro de liquidação; o cliente envia uma chave de idempotência para que um toque duplo não crie dois pedidos. |
| POST /api/v1/payments/callback | Callback do gateway. É idempotente no ID da transação do gateway, verifica a assinatura e avança o estado do pedido. Retorna sucesso somente depois que a alteração de estado é confirmada; caso contrário, o gateway continua tentando. |
| POST /api/v1/orders/{id}/cancel | Libera o estoque reservado e reverte o uso de cupons e pontos na mesma transação que encerra o pedido. |
| GET /api/v1/skus/{id}/availability | Lê o estoque disponível por meio do cache com um TTL curto. A disponibilidade exibida pode intencionalmente apresentar atraso; somente a transação do pedido é autoritativa. |
| POST /api/v1/admin/inventory/adjust | Grava um inventory_txn com um código de motivo e o ID do operador, em vez de atualizar diretamente um número de estoque. Toda correção manual permanece rastreável. |
Decisões técnicas
- UniApp em vez de mini programas nativos separados. WeChat e Douyin compartilham a maior parte do fluxo de comércio, portanto uma única base de código elimina a manutenção duplicada. Os pagamentos e logins específicos de cada plataforma são isolados atrás de uma camada de adaptadores, em vez de serem espalhados pelas páginas.
- Estoque reservado na criação do pedido, não no pagamento. Reservar no momento do pagamento significa que um cliente pode pagar por algo que já foi vendido. A contrapartida é que os pedidos não pagos mantêm o estoque reservado; por isso, as reservas expiram por um temporizador e um worker as libera.
- Disponibilidade derivada, nunca armazenada. Um valor cached available_qty introduz outro caminho de sincronização. A disponibilidade derivada pode reduzir essa duplicação; compare o desempenho de leitura e o comportamento de reconciliação para a carga de trabalho real.
- Livros-razão com registros apenas adicionados para estoque, pontos e saldo. Qualquer valor que os clientes possam contestar deve ser reconstruível a partir de um registro; caso contrário, o suporte não terá como explicar uma discrepância.
- Go para a camada de API. A carga de trabalho consiste em muitas solicitações curtas e concorrentes em torno de um banco de dados, o que se adapta ao modelo de concorrência do Go, e um único binário estático simplifica a implantação e a reversão.
Metas hipotéticas de projeto
Os números abaixo são exemplos hipotéticos de planejamento de capacidade, não resultados medidos de clientes, uma recomendação de dimensionamento validada ou um SLA. Defina metas de aceitação específicas do projeto após determinar a carga de trabalho, os dispositivos, os dados, o hardware e as dependências de terceiros; verifique-as por meio de um piloto e de testes de carga antes de assumir um objetivo de produção.
Metas de capacidade e desempenho
| Meta | Valor e premissa |
|---|---|
| Latência de leitura do catálogo | p95 inferior a 150 ms na API, pressupondo dados quentes no Redis e um banco de dados na mesma rede privada. |
| Criação de pedido | p95 inferior a 400 ms, incluindo a reserva de estoque, em um único banco de dados primário com tabelas de pedidos indexadas em (site_id, status, created_at). |
| Pico de venda relâmpago | Fluxo de pedidos dimensionado para alguns milhares de solicitações por minuto por SKU por meio de um decremento atômico no Redis antes da liquidação no MySQL. Acima disso, é adicionada uma admissão baseada em fila — o limite é confirmado por testes de carga com o volume de dados real. |
| Callback de pagamento | Processado de forma idempotente dentro da janela de novas tentativas do gateway; callbacks duplicados são rejeitados pelo ID exclusivo da transação do gateway. |
O que a entrega inclui
- Código-fonte do mini programa, do back-end Go e do administrador Vue no seu repositório
- Esquema do banco de dados com migrações, justificativa dos índices e tabelas do livro-razão documentadas
- Documentação da API cobrindo autenticação, códigos de erro e requisitos de idempotência
- Notas de implantação para Linux, Docker e Nginx, além do procedimento de backup e restauração
- Suporte à integração de contas de pagamento e mensagens; o resultado da análise da plataforma permanece sob responsabilidade do WeChat ou Douyin
Planejando isso para sua empresa
Os módulos acima são um ponto de partida, não um pacote fixo. Normalmente reduzimos a primeira versão a um fluxo principal mais um fluxo administrativo e, depois, ampliamos quando o uso real mostra onde a carga e os casos extremos realmente estão. Envie um briefing com escopo e vamos compará-lo com esta arquitetura e informar quais partes ainda não são necessárias.
