物流运营系统参考架构

应用参考。这是一个示例性架构和范围检查清单，并非经验证的客户项目或实测部署。技术、集成范围和交付项将根据实际需求确定。

场景与约束

某物流运营商正在替换电子表格调度和人工计费流程。设计由两个约束驱动：司机在信号不可靠的区域工作，并且客户对发票提出异议时，每一条发票明细都必须能够提供依据。因此，系统采用仅追加事件日志作为事实来源，而不是任何人都可以覆盖的状态列。

层级	技术	负责内容
运营 Web	Vue 3 + Element Plus	订单录入、调度看板、异常处理、计费审核。
司机应用	Android (Kotlin)，支持离线	任务列表、扫描、照片、签名和状态采集。所有内容先写入本地，连接可用时再上传。
客户门户	微信小程序	自助查询跟踪；应测量咨询量的任何变化，而不是假定咨询量会减少。
API	Go + Gin	校验、调度规则、事件接收、费用计算。
存储	MySQL	托运单、事件、结算。事件表为仅追加表，是系统的记录依据。
缓存 / 队列	Redis	调度看板缓存、上传去重、用于计费和通知的后台任务。
文件	对象存储	交付证明照片和签名，通过键引用，而不是存储在数据库中。

以下表格承载着其他所有部分所依赖的规则。若这些规则设计错误，能够运行的演示就会变成无法扩展的系统。

实体	关键字段、关系和规则
consignment	托运记录：参与方、地址、服务类型、时间窗口、申报重量和体积，以及录入时约定的计价依据。
shipment_event	仅追加、带时间戳，并包含操作员、位置、事件类型和事件数据内容。当前状态根据最新事件推导，而不是单独存储——这使时间线在争议中具备可证明性。
task / assignment	司机和车辆分配及停靠顺序，以及任务交接时的重新分配历史。
pod_asset	交付证明：照片和签名键、采集时间戳及设备位置，作为计费依据保存。
charge / invoice	根据已记录事件上的规则生成费用明细，每条明细都携带作为其依据的事件 ID。没有可追溯事件的发票明细将按设计被拒绝。
rate_card	按重量、体积、距离、等待时间和附加费制定的客户专属定价规则，并进行版本化，以便历史发票继续重现其原始金额。

端点	用途和并发说明
POST /api/v1/consignments	订单录入时进行地址地理编码和费率卡解析，从而在任务执行前固定计价依据。
POST /api/v1/events/batch	司机应用在连接中断后批量上传事件。根据客户端事件 UUID 去重，并将采集时间与接收时间分开存储，以保持时间线的真实性。
POST /api/v1/tasks/{id}/pod	上传带采集时间戳的签名和照片，并返回关联到托运单的存储键。
POST /api/v1/billing/run	根据某一期间的事件生成费用明细。以 (customer, period) 为单位保持幂等，因此重新运行会更正既有结果，而不是生成重复结果。
GET /api/v1/track/{no}	公开跟踪，使用缓存，仅披露客户可见的事件子集。

事件是事实来源，状态是推导值。可编辑的状态列会丢失争议处理所依赖的历史记录。推导状态需要一次连接查询，但能换来完整且可证明的审计轨迹。
分别存储采集时间和接收时间。司机在 14:02 扫描、17:30 上传的记录必须显示为 14:02，并注明已知的上传延迟；否则每个离线区域都会产生错误的时间线。
客户端生成事件 UUID。在连接质量较差时，上传重试是正常情况，因此去重必须依赖客户端拥有的标识符。
费率卡进行版本化，而不是直接编辑。价格变更不能悄悄重写上月发票，因此保留旧版本，并让历史费用继续指向这些版本。
生成计费结果但不自动开具。规则覆盖可计算的情形；任何需要人工判断的内容都进入审核队列，而不是被强行纳入自动化流程。

以下数字是用于容量规划的假设性示例，不是实测客户结果、经过验证的容量建议或 SLA。在明确工作负载、设备、数据、硬件和第三方依赖后，设定项目专属验收目标；在承诺生产目标前，通过试点和负载测试进行验证。

目标	数值和假设
事件接收	每次上传最多包含几百个事件的批次，进行去重，容量按离线数小时后恢复连接的司机进行设计。
调度看板	在少于 1 秒内渲染活动工作集，采用服务端筛选和分页，而不是将全部内容加载到浏览器中。
计费运行	将某一客户一个月的事件作为后台任务处理，并报告进度；运行时间随事件量变化，并在验收期间根据您的真实数据进行测量。
照片上传	上传前在本地压缩并排队，失败时重试，并在实际设备上验证保留、确认和恢复。

上述模块是起点，而不是固定套餐。我们通常会将第一个版本缩减为一个核心工作流加一个管理工作流，然后在真实使用情况显示实际负载和边界情况所在后再扩展。发送范围明确的需求说明，我们将根据此架构进行匹配，并告知您目前还不需要哪些部分。