Referencia de aplicación. Se trata de una arquitectura ilustrativa y una lista de comprobación del alcance, no de un proyecto de cliente verificado ni de una implementación con resultados medidos. Las tecnologías, el alcance de la integración y los elementos de entrega se acuerdan para el encargo concreto.
Escenario y restricciones
Un operador logístico que sustituye las hojas de cálculo para la asignación de servicios y la facturación manual. Dos restricciones determinan el diseño: los conductores trabajan en zonas sin señal fiable y cada partida de factura debe poder justificarse cuando un cliente la impugna. Esto orienta el sistema hacia un registro de eventos de solo anexado como fuente de verdad, en lugar de una columna de estado que cualquiera pueda sobrescribir.
Arquitectura
Capas y responsabilidades
| Capa | Tecnología | Responsabilidad |
|---|---|---|
| Web de operaciones | Vue 3 + Element Plus | Recepción de pedidos, panel de asignación, gestión de excepciones y revisión de facturación. |
| Aplicación del conductor | Android (Kotlin), compatible con el modo sin conexión | Lista de tareas, escaneo, fotos, firmas y registro de estados. Todo se guarda primero de forma local y se carga cuando hay conexión disponible. |
| Portal del cliente | Miniprograma de WeChat | Seguimiento de autoservicio; medir cualquier cambio en el volumen de consultas en vez de dar por sentada una reducción. |
| API | Go + Gin | Validación, reglas de asignación, recepción de eventos y cálculo de cargos. |
| Almacenamiento | MySQL | Envíos, eventos y liquidación. La tabla de eventos es de solo anexado y constituye el registro del sistema. |
| Caché / cola | Redis | Almacenamiento en caché del panel de asignación, deduplicación de cargas y tareas en segundo plano para facturación y notificaciones. |
| Archivos | Almacenamiento de objetos | Fotos y firmas de comprobantes de entrega, referenciadas por clave en lugar de almacenarse en la base de datos. |
Modelo de datos
Las tablas siguientes contienen las reglas de las que depende todo lo demás. Si se definen mal, una demostración funcional puede convertirse en un sistema imposible de ampliar.
Entidades principales
| Entidad | Campos clave, relaciones y reglas |
|---|---|
| consignment | Registro del envío: partes, direcciones, tipo de servicio, franjas horarias, peso y volumen declarados, y base de precios acordada al recibir el pedido. |
| shipment_event | De solo anexado, con marca de tiempo, operador, ubicación, tipo de evento y carga útil. El estado actual se deriva del evento más reciente, no se almacena por separado; esto permite justificar la cronología en caso de disputa. |
| task / assignment | Asignación de conductor y vehículo con secuencia de paradas, además del historial de reasignaciones cuando se transfiere un trabajo. |
| pod_asset | Comprobante de entrega: claves de fotos y firmas, marca de tiempo de captura y ubicación del dispositivo, que se conservan como evidencia de la facturación. |
| charge / invoice | Partidas de cargo generadas a partir de reglas aplicadas a los eventos registrados; cada una incluye el id del evento que la justifica. Por diseño, se rechaza toda partida de factura sin un evento trazable. |
| rate_card | Reglas de precios específicas para cada cliente, basadas en peso, volumen, distancia, tiempo de espera y recargos, con control de versiones para que las facturas históricas sigan reproduciendo sus importes originales. |
Interfaces clave
Endpoints que contienen las reglas de negocio
| Endpoint | Finalidad y consideraciones de concurrencia |
|---|---|
| POST /api/v1/consignments | Recepción de pedidos con geocodificación de direcciones y resolución de la tarifa en el momento de la creación, de modo que la base de precios quede fijada antes de que se ejecute el trabajo. |
| POST /api/v1/events/batch | Carga masiva de eventos desde la aplicación del conductor tras un periodo sin conexión. Se deduplica mediante un UUID de evento del cliente y se almacena por separado la hora de captura y la hora de recepción para mantener la veracidad de la cronología. |
| POST /api/v1/tasks/{id}/pod | Carga firmas y fotos con la marca de tiempo de captura y devuelve claves de almacenamiento que se vinculan al consignment. |
| POST /api/v1/billing/run | Genera partidas de cargo a partir de los eventos de un periodo. Es idempotente por (cliente, periodo), de modo que una nueva ejecución corrige los resultados en lugar de duplicarlos. |
| GET /api/v1/track/{no} | Seguimiento público en caché que expone únicamente el subconjunto de eventos visible para el cliente. |
Decisiones técnicas
- Los eventos son la fuente de verdad; el estado es un valor derivado. Una columna de estado editable pierde el historial del que depende la gestión de disputas. Derivar el estado requiere una unión y proporciona un registro de auditoría completo y justificable.
- La hora de captura y la hora de recepción se almacenan por separado. El escaneo de un conductor a las 14:02, cargado a las 17:30, debe mostrarse como ocurrido a las 14:02 con una demora de carga conocida; de lo contrario, cada zona sin conexión generará una cronología incorrecta.
- UUID de eventos generados por el cliente. Reintentar cargas es normal con conexiones deficientes, por lo que la deduplicación debe basarse en un identificador que pertenezca al cliente.
- Las tarifas tienen control de versiones, en lugar de editarse. Un cambio de precio no debe modificar silenciosamente las facturas del mes pasado, por lo que se conservan las versiones anteriores y los cargos históricos siguen apuntando a ellas.
- La facturación se genera, pero no se emite automáticamente. Las reglas cubren los casos calculables; todo lo que requiera criterio humano se envía a una cola de revisión, en lugar de forzarse dentro de la automatización.
Objetivos de diseño hipotéticos
Las cifras siguientes son ejemplos hipotéticos para la planificación de capacidad, no resultados medidos de clientes, recomendaciones de dimensionamiento validadas ni un SLA. Establezca objetivos de aceptación específicos para el 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 |
|---|---|
| Recepción de eventos | Lotes de hasta unos cientos de eventos por carga, deduplicados y dimensionados para un conductor que regresa tras varias horas sin conexión. |
| Panel de asignación | Renderiza el conjunto de trabajo activo en menos de 1 segundo, con filtrado y paginación en el servidor en vez de cargarlo todo en el navegador. |
| Ejecución de facturación | Los eventos de un mes para un cliente se procesan como una tarea en segundo plano con informes de progreso; el tiempo de ejecución depende del volumen de eventos y se mide con sus datos reales durante la aceptación. |
| Carga de fotos | Comprimir y poner en cola localmente antes de la carga, reintentar en caso de fallo y verificar la retención, la confirmación y la recuperación en los dispositivos reales. |
Qué incluye la entrega
- Código fuente de la web de operaciones, el backend en Go, la aplicación Android para conductores y el miniprograma
- Esquema de base de datos con documentación de las tablas de eventos y liquidación, además del historial de migraciones
- Documentación de la API, incluido el contrato de carga sin conexión y deduplicación
- Notas de despliegue, configuración del almacenamiento de objetos y procedimiento de copia de seguridad y restauración
- Plan de migración de datos desde las hojas de cálculo existentes, con un informe de conciliación posterior a la importación
Planificación para su empresa
Los módulos anteriores son un punto de partida, no un paquete fijo. Normalmente limitamos la primera versión a un flujo de trabajo principal y uno administrativo; después ampliamos la solución cuando el uso real muestra dónde están la carga y los casos límite. Envíenos una descripción del alcance y la contrastaremos con esta arquitectura para indicarle qué partes todavía no necesita.
