Referencia de aplicación. Esta es una arquitectura ilustrativa y una lista de comprobación del alcance, no un proyecto real de cliente verificado ni una implementación con métricas. Las tecnologías, el alcance de la integración y los elementos de entrega se acuerdan para el encargo real.
Escenario y restricciones
Una marca minorista que vende a través de un miniprograma de WeChat y que también gestiona tiendas físicas. El requisito crítico es que el inventario se mantenga correcto en todos los canales durante las promociones: el inventario actualizado de forma independiente en cada canal puede crear riesgo de sobreventa si no se definen reglas de reserva, sincronización y conciliación. Los puntos de membresía y los cupones también deben liquidarse de forma coherente, porque aplicar un descuento dos veces supone una pérdida financiera directa.
Arquitectura
Capas y responsabilidades
| Capa | Tecnología | Responsabilidad |
|---|---|---|
| Cliente | UniApp (WeChat + Douyin desde una base de código) | Exploración del catálogo, carrito, pago y centro de miembros. Ninguna regla de negocio se considera fiable aquí; el cliente solo muestra el estado confirmado por el servidor. |
| API | Go + Gin, sin estado detrás de un balanceador de carga | Validación de solicitudes, autenticación, reglas de negocio y límites de las transacciones. Escalable horizontalmente porque el proceso no conserva el estado de sesión. |
| Caché | Redis | Datos activos del catálogo, contadores de inventario para ventas relámpago, bloqueos distribuidos y claves de idempotencia para las devoluciones de llamada de pago. |
| Almacenamiento | MySQL con réplica de lectura | Datos de referencia. Las escrituras se dirigen al principal; las lecturas del catálogo y de informes pueden dirigirse a una réplica cuando la carga de lectura lo justifique. |
| Administración | Vue 3 + Element Plus | Gestión del catálogo, pedidos, inventario, promociones y tiendas, con permisos aplicados por el backend. |
| Asíncrono | Trabajadores de cola | Conciliación de pagos, envío de mensajes, agregación de informes y liberación de inventario cuando caduca un pedido, es decir, cualquier tarea que no deba bloquear la solicitud de finalización de compra. |
Modelo de datos
Las tablas siguientes contienen las reglas de las que depende todo lo demás. Equivocarse aquí es lo que convierte una demostración funcional en un sistema que no puede ampliarse.
Entidades principales
| Entidad | Campos clave, relaciones y reglas |
|---|---|
| producto / sku | Un producto se relaciona con muchos SKU mediante la combinación de atributos. El precio y el inventario dependen del SKU, nunca del producto; de lo contrario, sería imposible ampliar los precios con múltiples variantes. |
| inventario | Filas identificadas por (sku_id, location_id) que contienen on_hand y reserved. El inventario disponible se obtiene como on_hand menos reserved; las transacciones y la conciliación aún deben probarse para detectar discrepancias. |
| inventory_txn | Libro mayor de solo adición de cada movimiento de inventario, con código de motivo y pedido de origen. El inventario actual siempre debe poder reproducirse reproduciendo este libro mayor; así las discrepancias pueden auditarse en lugar de ser objeto de discusión. |
| pedido / order_item | El pedido contiene la máquina de estados y los totales; los artículos guardan una instantánea del título, la especificación y el precio unitario del SKU en el momento de la compra, para que las modificaciones posteriores del catálogo no puedan reescribir el historial del pedido. |
| payment_txn | Id. de transacción de la pasarela, importe, estado y contenido sin procesar de la devolución de llamada. Es único según el id. de la pasarela, de modo que una devolución de llamada repetida de WeChat Pay no pueda aplicarse dos veces. |
| miembro / point_txn / cupón | El saldo y los puntos del miembro se obtienen de un registro de transacciones de solo adición. Las filas de cupones contienen el alcance, el umbral, la prioridad de acumulación y una marca used_at utilizada para hacer cumplir el uso único. |
Interfaces clave
Endpoints que contienen las reglas de negocio
| Endpoint | Propósito y notas sobre concurrencia |
|---|---|
| POST /api/v1/orders | Crea el pedido y reserva el inventario dentro de una única transacción de base de datos. Con carga de venta relámpago, la reserva pasa primero por un decremento atómico en Redis, mientras que MySQL actúa como registro de liquidación; el cliente envía una clave de idempotencia para que un doble toque no cree dos pedidos. |
| POST /api/v1/payments/callback | Devolución de llamada de la pasarela. Es idempotente según el id. de transacción de la pasarela, verifica la firma y hace avanzar el estado del pedido. Devuelve éxito solo después de confirmar el cambio de estado; de lo contrario, la pasarela sigue reintentando. |
| POST /api/v1/orders/{id}/cancel | Libera el inventario reservado y revierte el uso de cupones y puntos en la misma transacción que cierra el pedido. |
| GET /api/v1/skus/{id}/availability | Lee el inventario disponible mediante una caché con un TTL breve. Se permite intencionadamente que la disponibilidad mostrada tenga cierto retraso; solo la transacción del pedido es la fuente de autoridad. |
| POST /api/v1/admin/inventory/adjust | Escribe un inventory_txn con un código de motivo y el id. del operador en lugar de actualizar directamente una cifra de inventario. Toda corrección manual sigue siendo trazable. |
Decisiones técnicas
- UniApp en lugar de miniprogramas nativos separados. WeChat y Douyin comparten la mayor parte del flujo comercial, por lo que una sola base de código elimina el mantenimiento duplicado. Los pagos y los inicios de sesión específicos de cada plataforma se aíslan tras una capa de adaptadores en lugar de distribuirse por las páginas.
- Inventario reservado al crear el pedido, no al pagar. Reservar en el momento del pago significa que un cliente puede pagar por algo que ya se ha vendido. La contrapartida es que los pedidos impagados retienen inventario, por lo que las reservas caducan mediante un temporizador y un trabajador las libera.
- Disponibilidad calculada, nunca almacenada. Un valor de available_qty almacenado en caché introduce otra ruta de sincronización. La disponibilidad calculada puede reducir esa duplicación; compare el rendimiento de lectura y el comportamiento de conciliación para la carga de trabajo real.
- Libros mayores de solo adición para inventario, puntos y saldo. Cualquier cifra que los clientes puedan cuestionar debe poder reconstruirse a partir de un registro; de lo contrario, el equipo de soporte no tiene forma de explicar una discrepancia.
- Go para la capa de API. La carga de trabajo consiste en muchas solicitudes breves y concurrentes alrededor de una base de datos, lo que se adapta al modelo de concurrencia de Go, y un único binario estático simplifica el despliegue y la reversión.
Objetivos de diseño hipotéticos
Las cifras siguientes son ejemplos hipotéticos de planificación de capacidad, no resultados medidos de un cliente, una recomendación de dimensionamiento validada ni un SLA. Establezca objetivos de aceptación específicos del proyecto después de definir la carga de trabajo, los dispositivos, los datos, el hardware y las dependencias de terceros; verifíquelos mediante un piloto y pruebas de carga antes de comprometerse con un objetivo de producción.
Objetivos de capacidad y rendimiento
| Objetivo | Valor y supuesto |
|---|---|
| Latencia de lectura del catálogo | p95 inferior a 150 ms en la API, suponiendo que los datos activos estén en Redis y que la base de datos se encuentre en la misma red privada. |
| Creación de pedidos | p95 inferior a 400 ms, incluida la reserva de inventario, en una única base de datos principal con las tablas de pedidos indexadas en (site_id, status, created_at). |
| Pico de venta relámpago | Ruta de pedidos dimensionada para unos pocos miles de solicitudes por minuto por SKU mediante un decremento atómico en Redis antes de la liquidación en MySQL. Más allá de ese nivel, se añade admisión basada en colas; el umbral se confirma mediante pruebas de carga con el volumen de datos real. |
| Devolución de llamada de pago | Procesada de forma idempotente dentro de la ventana de reintento de la pasarela; las devoluciones de llamada duplicadas se rechazan según el id. de transacción único de la pasarela. |
Qué incluye la entrega
- Código fuente del miniprograma, del backend en Go y del panel de administración en Vue en su repositorio
- Esquema de base de datos con migraciones, justificación de los índices y documentación de las tablas del libro mayor
- Documentación de la API que cubre la autenticación, los códigos de error y los requisitos de idempotencia
- Notas de despliegue para Linux, Docker y Nginx, además del procedimiento de copia de seguridad y restauración
- Asistencia para la integración de cuentas de pago y mensajería; el resultado de la revisión de la plataforma sigue correspondiendo a WeChat o Douyin
Planificación para su negocio
Los módulos anteriores son un punto de partida, no un paquete fijo. Normalmente reducimos la primera versión a un flujo de trabajo principal y un flujo de administración, y después la ampliamos cuando el uso real muestra dónde se encuentran realmente la carga y los casos límite. Envíe un documento de requisitos con el alcance y lo compararemos con esta arquitectura para indicarle qué partes todavía no necesita.
