三方物流平台-TMS 智慧运输管理系统

1. 架构概述

1.1 架构风格

基于 yudao-cloud 的微服务架构 + 事件驱动

1.2 设计原则

原则	说明
高可用	多活部署、故障自动转移
可扩展	水平扩展能力、弹性伸缩
安全性	数据加密、访问控制、审计日志
可观测	全链路追踪、监控告警、日志分析
一致性	遵循 yudao-cloud 技术规范

1.3 架构分层

复制代码

┌─────────────────────────────────────────────────────────────┐
│                     接入层 (Access Layer)                   │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │
│  │  PC端   │ │  司机APP │ │ 移动端  │ │ 小程序  │          │
│  │(MateClaw)│ │(MateClaw)│ │(UniApp) │ │(UniApp) │       │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘          │
└───────┼───────────┼───────────┼───────────┼───────────────┘
        │           │           │           │
┌───────▼───────────▼───────────▼───────────▼───────────────┐
│                   网关层 (API Gateway)                      │
│       路由转发 | 负载均衡 | 认证授权 | 限流熔断              │
│         [yudao-gateway]                                   │
└──────────────────────┬─────────────────────────────────────┘
                       │
┌──────────────────────▼─────────────────────────────────────┐
│                  业务服务层 (Service Layer)                 │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐   │
│  │tms-dispatch│ │tms-transport│ │tms-fleet│ │tms-billing│   │
│  └───────────┘ └───────────┘ └───────────┘ └───────────┘   │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐   │
│  │tms-coldchain││tms-border││tms-reverse││tms-report │   │
│  └───────────┘ └───────────┘ └───────────┘ └───────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          tms-plan (计划物流模块)                    │   │
│  │  需求预测 | 运力预排 | 路线优化 | 计划监控         │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          yudao-boot-starter 基础设施支撑            │   │
│  │  权限认证 | 数据权限 | 异常处理 | 参数校验 | 日志   │   │
│  └─────────────────────────────────────────────────────┘   │
└──────────────────────┬─────────────────────────────────────┘
                       │
┌──────────────────────▼─────────────────────────────────────┐
│                  数据层 (Data Layer)                        │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐          │
│  │  MySQL主库  │ │   Redis    │ │  RocketMQ   │          │
│  │ (业务数据)  │ │ (缓存/会话) │ │  (消息队列) │          │
│  └──────┬──────┘ └─────────────┘ └─────────────┘          │
│         │                                                  │
│  ┌──────▼──────┐                                           │
│  │ MySQL从库   │                                           │
│  │ (读写分离)  │                                           │
│  └─────────────┘                                           │
└─────────────────────────────────────────────────────────────┘

2. 技术选型

2.1 核心技术栈

分类	技术	版本	选型理由
语言	Java	21	LTS 版本，yudao-cloud 标准
框架	Spring Boot	3.2.x	yudao-cloud 基础框架
微服务	Spring Cloud	2023.x	yudao-cloud 微服务体系
数据库	MySQL	8.0+	yudao-cloud 默认数据库
缓存	Redis	7.0+	yudao-cloud 缓存方案
消息队列	RocketMQ	5.1.x	yudao-cloud 默认消息队列
搜索	Elasticsearch	8.13+	全文检索能力强
ORM	MyBatis Plus	3.5.x	yudao-cloud ORM框架
网关	Spring Cloud Gateway	4.0+	yudao-cloud 网关组件
配置中心	Nacos	2.3+	配置与服务发现
链路追踪	SkyWalking	9.7+	分布式链路追踪
前端框架	MateClaw	2.x	基于 Vue3 的企业级框架

2.2 yudao-cloud 核心组件集成

组件	说明	集成方式
yudao-common	通用工具类、异常处理	Maven依赖
yudao-spring-boot-starter-security	认证授权、JWT	Maven依赖
yudao-spring-boot-starter-data-redis	Redis配置、分布式锁	Maven依赖
yudao-spring-boot-starter-datasource	多数据源、读写分离	Maven依赖
yudao-spring-boot-starter-web	Web配置、全局异常处理	Maven依赖

3. 模块划分与职责

3.1 微服务模块划分

服务名称	模块名称	职责描述	核心功能
tms-dispatch	智能调度模块	订单调度、派车管理	自动匹配、路线规划、批量派单
tms-transport	运输跟踪模块	运单全周期管理	GPS追踪、在途监控、电子签收
tms-fleet	运力管理模块	车辆/司机/承运商管理	运力池、评级体系、资质管理
tms-billing	计费管理模块	运费计算与结算	差价协调、费用核算、对账
tms-coldchain	冷链管控模块	冷链运输管理	温控监控、双温分区、封签追溯
tms-border	跨境运输模块	跨境报关清关	报关申报、查验追踪、国际运输
tms-reverse	逆向物流模块	退货召回管理	退货流程、召回执行、库存处理
tms-report	数据分析模块	报表与KPI分析	运营报表、绩效分析、成本核算
tms-plan	计划物流模块	ToB计划配送管理	需求预测、运力预排、路线优化

3.2 目录结构（遵循 yudao-cloud 规范）

复制代码

backend/
├── yudao-module-tms/                    # TMS 模块根目录
│   ├── yudao-module-tms-api/            # API 层（DTO、枚举、Feign接口）
│   │   ├── src/main/java/
│   │   │   └── com/yudao/module/tms/api/
│   │   │       ├── dispatch/            # 调度API
│   │   │       ├── transport/           # 运输API
│   │   │       ├── fleet/               # 运力API
│   │   │       └── plan/                # 计划物流API
│   │   └── src/main/resources/
│   ├── yudao-module-tms-service/        # Service 层（业务逻辑）
│   │   ├── src/main/java/
│   │   │   └── com/yudao/module/tms/service/
│   │   │       ├── dispatch/
│   │   │       ├── transport/
│   │   │       └── impl/                # 实现类
│   │   └── src/main/resources/
│   │       └── mapper/                  # MyBatis Mapper XML
│   ├── yudao-module-tms-dal/            # DAL 层（数据访问）
│   │   └── src/main/java/
│   │       └── com/yudao/module/tms/dal/
│   │           ├── entity/              # 实体类
│   │           └── mapper/               # Mapper 接口
│   └── yudao-module-tms-biz/            # 启动模块
│       └── src/main/java/
│           └── com/yudao/module/tms/
│               ├── TmsApplication.java   # 启动类
│               └── controller/          # REST Controller
└── pom.xml                              # Maven 依赖管理

3.3 前端架构（基于 MateClaw）

模块名称	说明	技术栈
tms-pc	PC端管理后台	Vue3 + MateClaw + TypeScript
tms-driver	司机APP	Vue3 + MateClaw
tms-mini	货主小程序	UniApp + Vue3

4. 关键数据库设计

4.1 核心数据表

表名	说明	核心字段
`tms_waybill`	运单表	id, waybill_no, status, create_time
`tms_vehicle`	车辆表	id, plate_no, model, capacity, status
`tms_driver`	司机表	id, name, license_no, phone, status
`tms_carrier`	承运商表	id, name, rating, audit_status
`tms_route`	线路表	id, start_point, end_point, distance
`tms_track`	轨迹表	id, waybill_id, latitude, longitude, track_time
`tms_fence`	电子围栏表	id, name, type, coordinates
`tms_coldchain_record`	冷链记录表	id, waybill_id, temperature, humidity
`tms_delivery_plan`	配送计划表	id, plan_no, customer_id, plan_date, status
`tms_plan_detail`	计划明细表	id, plan_id, order_id, delivery_point, time_window
`tms_route_plan`	路线规划表	id, plan_id, vehicle_id, route_sequence, distance
`tms_resource_alloc`	资源分配表	id, plan_id, vehicle_id, driver_id, carrier_id
`tms_plan_kpi`	计划KPI表	id, plan_id, on_time_rate, load_rate, cost
`tms_plan_exception`	计划异常表	id, plan_id, exception_type, handle_status

4.2 ER关系图

复制代码

tms_vehicle 1 ─── * tms_driver
tms_carrier 1 ─── * tms_vehicle
tms_waybill 1 ─── * tms_track
tms_waybill 1 ─── * tms_coldchain_record
tms_fence 1 ─── * tms_waybill
tms_delivery_plan 1 ─── * tms_plan_detail
tms_delivery_plan 1 ─── * tms_route_plan
tms_delivery_plan 1 ─── * tms_resource_alloc
tms_delivery_plan 1 ─── * tms_plan_kpi
tms_delivery_plan 1 ─── * tms_plan_exception

4.3 索引设计

表名	索引字段	索引类型	用途
`tms_waybill`	waybill_no, status	复合索引	运单查询
`tms_track`	waybill_id, track_time	复合索引	轨迹查询
`tms_vehicle`	status, carrier_id	复合索引	车辆查询
`tms_coldchain_record`	waybill_id	普通索引	温控查询

5. API接口设计

5.1 调度管理接口

API路径	HTTP方法	功能描述
`/api/tms/dispatch/orders`	POST	创建调度订单
`/api/tms/dispatch/orders/{id}`	GET	查询订单详情
`/api/tms/dispatch/assign`	POST	派车分配
`/api/tms/dispatch/wave`	POST	批量派单

5.2 运输跟踪接口

API路径	HTTP方法	功能描述
`/api/tms/transport/track/{waybillNo}`	GET	查询轨迹
`/api/tms/transport/sign/{waybillNo}`	POST	电子签收
`/api/tms/transport/exception`	POST	异常上报
`/api/tms/transport/status/{waybillNo}`	GET	查询状态

5.3 运力管理接口

API路径	HTTP方法	功能描述
`/api/tms/fleet/vehicles`	GET	查询车辆列表
`/api/tms/fleet/drivers`	GET	查询司机列表
`/api/tms/fleet/carriers`	GET	查询承运商列表
`/api/tms/fleet/assign`	POST	运力分配

5.4 计划物流接口

API路径	HTTP方法	功能描述
`/api/tms/plan/create`	POST	创建配送计划
`/api/tms/plan/forecast`	POST	需求预测
`/api/tms/plan/optimize`	POST	路线优化规划
`/api/tms/plan/monitor/{planId}`	GET	计划执行监控
`/api/tms/plan/kpi/{planId}`	GET	计划KPI分析
`/api/tms/plan/exceptions`	GET	计划异常列表

5.5 API响应格式（遵循 yudao-cloud 规范）

复制代码

{
  "code": 200,
  "message": "操作成功",
  "data": { ... },
  "timestamp": 1704067200000,
  "traceId": "abc123def456"
}

6. 部署架构

6.1 物理部署架构

复制代码

┌─────────────────────────────────────────────────────────────────┐
│                        公网入口                                  │
│                       [Nginx LB]                                │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                    服务网关层                                    │
│           [yudao-gateway] x 3 (集群部署)                       │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                    业务服务层                                    │
│  [tms-dispatch] [tms-transport] [tms-fleet] [tms-billing]     │
│       x3           x3            x3           x3               │
└──────────────────────────────┬──────────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────────┐
│                    数据存储层                                    │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐               │
│  │ MySQL (主)  │ │   Redis     │ │  RocketMQ   │               │
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘               │
│         │               │               │                       │
│  ┌──────▼──────┐       │       ┌─────────────┐                 │
│  │ MySQL (从)  │       │       │ Elasticsearch│                 │
│  └─────────────┘       │       └─────────────┘                 │
└─────────────────────────────────────────────────────────────────┘

6.2 网络分区

区域	说明	安全级别
DMZ区	外网入口，Nginx负载均衡	低
服务区	网关与业务服务	中
数据区	数据库与缓存	高

6.3 配置与监控组件

组件	说明
Nacos	配置中心 + 服务发现
SkyWalking	分布式链路追踪
Prometheus + Grafana	监控告警
ELK	日志收集与分析

7. 安全架构

7.1 认证与授权

认证方式	适用场景	说明
JWT Token	PC端、移动端、司机APP	yudao-cloud 默认认证
OAuth 2.0	第三方系统对接	授权码模式
API Key	内部系统调用	固定密钥认证

权限模型：RBAC + 数据权限（基于 yudao-cloud）

7.2 安全注解使用规范

注解	用途	示例
`@PreAuthorize("@ss.hasPermission('tms:dispatch:create')")`	方法级权限校验	控制调度订单创建
`@DataPermission(deptAlias = "c")`	数据权限过滤	过滤用户可见的承运商
`@LoginUser`	获取当前登录用户	获取操作人信息

8. 业务流程图

8.1 调度派车流程

复制代码

flowchart TD
    A[订单创建] --> B[运力匹配]
    B --> C[路线规划]
    C --> D[派单确认]
    D --> E[司机接单]
    E --> F[装车确认]
    F --> G[发车]

8.2 运输跟踪流程

复制代码

flowchart TD
    A[发车] --> B[GPS定位]
    B --> C[轨迹记录]
    C --> D{异常检测}
    D -->|正常| E[到达目的地]
    D -->|异常| F[异常上报]
    E --> G[电子签收]
    G --> H[回单归档]

8.3 逆向物流流程

复制代码

flowchart TD
    A[退货申请] --> B[上门取件]
    B --> C[运输回仓]
    C --> D[仓库质检]
    D --> E{分类处理}
    E -->|良品| F[重新入库]
    E -->|不良品| G[退回供应商]
    E -->|残次品| H[报废处理]

9. 性能指标与容量规划

9.1 性能指标

指标	目标值
接口响应时间	P95 < 200ms
订单处理能力	50000单/天
GPS定位频率	1次/分钟/车辆
数据同步延迟	< 1秒
系统可用性	99.9%

9.2 容量规划

10. ToB计划物流配送扩展

10.1 计划物流配送业务流程

复制代码

flowchart TD
    A[客户订单计划] --> B[需求预测]
    B --> C[运力资源预排]
    C --> D[路线优化规划]
    D --> E[计划确认]
    E --> F[计划执行调度]
    F --> G[在途监控]
    G --> H[异常预警]
    H --> I[回单结算]
    I --> J[KPI分析]
    J --> K[计划优化迭代]

10.2 ToB计划物流核心功能模块

功能模块	核心能力	技术实现
需求预测	基于历史数据智能预测配送需求	AI机器学习算法、时间序列分析
运力预排	车辆、司机、承运商资源计划配置	资源优化算法、甘特图可视化
路线规划	多点配送路线智能优化	遗传算法、模拟退火、蚁群算法
时间窗管理	客户收货时间窗口约束优化	约束规划算法
多仓协同	多仓库、多网点联合配送	Milk-Run模型优化
计划监控	计划执行进度实时监控	看板系统、进度追踪
异常预警	计划偏差、配送异常智能预警	规则引擎、实时监控
KPI考核	准时率、装载率、成本等指标分析	数据看板、报表系统

10.3 ToB计划物流数据模型扩展

表名	说明	核心字段
`tms_delivery_plan`	配送计划表	id, plan_no, customer_id, plan_date, status
`tms_plan_detail`	计划明细表	id, plan_id, order_id, delivery_point, time_window
`tms_route_plan`	路线规划表	id, plan_id, vehicle_id, route_sequence, distance
`tms_resource_alloc`	资源分配表	id, plan_id, vehicle_id, driver_id, carrier_id
`tms_plan_kpi`	计划KPI表	id, plan_id, on_time_rate, load_rate, cost
`tms_plan_exception`	计划异常表	id, plan_id, exception_type, handle_status

10.4 ToB计划物流API扩展

API路径	HTTP方法	功能描述
`/api/tms/plan/create`	POST	创建配送计划
`/api/tms/plan/forecast`	POST	需求预测
`/api/tms/plan/optimize`	POST	路线优化规划
`/api/tms/plan/monitor/{planId}`	GET	计划执行监控
`/api/tms/plan/kpi/{planId}`	GET	计划KPI分析
`/api/tms/plan/exceptions`	GET	计划异常列表

10.6 水平扩展

无状态服务：业务服务设计为无状态，支持弹性伸缩
数据库读写分离：主库写，从库读
缓存分片：Redis Cluster支持数据分片

10.7 事件驱动

RocketMQ消息队列：解耦业务流程，支持异步处理
事件溯源：记录所有状态变更事件

10.8 灰度发布

蓝绿部署：支持无停机发布
流量切分：按比例分配流量到新版本