# TMS 运输管理系统

**Repository Path**: MerlinRong/TMS

## Basic Information

- **Project Name**: TMS 运输管理系统
- **Description**: TMS 运输管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-07
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🚛 TMS 运输管理系统

**基于 FastAPI + Vue3 的前后端分离运输管理系统**

运输计划 · 车辆管理 · 路线管理 · 在途跟踪 · 运费结算

[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.11x-009688?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
[![Vue](https://img.shields.io/badge/Vue-3.4-4FC08D?logo=vuedotjs&logoColor=white)](https://vuejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Element Plus](https://img.shields.io/badge/Element_Plus-2.6-409EFF)](https://element-plus.org/)
[![Tests](https://img.shields.io/badge/Tests-48%20passed-3DDC84)](#-测试)
[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)

</div>

---

## 📖 简介

TMS（Transportation Management System）提供从 **订单接入 → 智能拼载 → 自动调度 → 在途跟踪 → 运费结算** 的运输全生命周期管理能力，与 ERP 物流模块互补。

核心亮点：

- ⚡ **异步优先**：FastAPI 全链路 `async/await`，SQLite 零依赖启动，可平滑切换 MySQL/Redis
- 🧠 **智能调度**：拼载推荐（时间窗/货物兼容/装载率）+ 评分算法自动选车（成本/时效/顺路）
- 🔒 **并发安全**：Redis 分布式锁 + 数据库乐观锁双保险，杜绝车辆重复分配
- 💰 **可插拔计费**：策略模式实现的 5 种计费规则引擎，新增模式零侵入
- 📡 **实时跟踪**：GPS 接入管道 + 电子围栏 + 路线偏离预警（防抖）+ WebSocket 推送

## 🗂 项目结构

```text
TMS/
├── 🐍 backend/     # FastAPI 后端（六业务模块 + core 基础设施 + 48 测试）
├── 🖼 frontend/    # Vue3 前端（Vite + Pinia + Element Plus，11 页面）
└── 🐳 deploy/      # 部署编排（预留）
```

## ✨ 功能模块

| 模块 | 功能 | 状态 |
|------|------|------|
| 📋 运输计划 | 订单 CRUD / CSV 导入 / 审核状态机 / 智能拼载 / 自动调度 / 冲突检测 | ✅ |
| 🚛 车辆管理 | 车辆·司机档案 / 状态终态保护 / 保险到期 30·15·7 天提醒 | ✅ |
| 🗺 路线管理 | 地图适配器（Mock/高德可切换）/ 里程与 ETA 计算 | ✅ |
| 📍 在途跟踪 | GPS 接入管道 / 实时位置 / 电子围栏 / 偏离预警 / 异常工单 / WebSocket | ✅ |
| 💰 运费结算 | 5 种计费策略 / 账单幂等生成 / 对账差异 / 逐级审批 | ✅ |
| ⚙️ 系统支撑 | JWT 认证 / RBAC 权限 / 审计日志 / AES 字段加密 / 分布式锁 | ✅ |

## 🚀 快速开始

### 环境要求

- Python 3.10+
- Node.js 18+

### 1️⃣ 启动后端（默认 SQLite，零外部依赖）

```bash
cd backend
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt    # Windows
# .venv/bin/pip install -r requirements.txt      # Linux / macOS

.venv\Scripts\uvicorn app.main:app --reload
```

> API 文档：<http://localhost:8000/docs>（Swagger UI）

### 2️⃣ 启动前端

```bash
cd frontend
npm install
npm run dev
```

> 访问 <http://localhost:5173>（开发模式已代理 `/api` 到后端 8000 端口）

### 3️⃣ 登录

| 用户名 | 密码 | 说明 |
|--------|------|------|
| `admin` | `admin123` | 首次启动自动创建，拥有全部权限 |

### 4️⃣ 体验 GPS 跟踪（可选）

```bash
# 先从 /docs 登录获取 token
.venv\Scripts\python tools/gps_simulator.py --token <JWT> --device <车辆GPS设备ID>
```

## 🧪 测试

```bash
# 后端：48 个单元 + 接口测试
cd backend && .venv\Scripts\python -m pytest tests/ -v

# 前端：构建校验
cd frontend && npm run build
```

## 🔌 切换生产级组件

所有中间件通过 `.env` 环境变量切换（模板见 `backend/.env.example`）：

| 变量 | 默认（零依赖） | 生产建议 |
|------|---------------|---------|
| `DATABASE_URL` | SQLite | MySQL 8.0（asyncmy） |
| `REDIS_URL` | 内存缓存 | Redis 7 |
| `MAP_PROVIDER` | mock | amap（高德） |
| `FIELD_ENCRYPT_KEY` | - | 强随机密钥 |

## 🛠 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Python 3.10+ · FastAPI · SQLAlchemy 2.0 (Async) · Pydantic V2 |
| 前端 | Vue 3 (Composition API) · TypeScript · Vite · Pinia · Element Plus · ECharts · SCSS |
| 安全 | JWT (OAuth2) · RBAC · AES-GCM 加密 · 审计日志 |
| 架构 | 状态机集中管理 · 策略模式计费引擎 · 工厂模式地图适配 · Redis 分布式锁 |

## 📚 文档

需求规格说明书（SRS）、系统设计文档（SDD）、编码实现方案位于 `.codebuddy/docs/`（本地文档目录，不入库）。

## 📄 License

[MIT](LICENSE)