# XETMS-FASTAPI

**Repository Path**: zhiops/xetms-fastapi

## Basic Information

- **Project Name**: XETMS-FASTAPI
- **Description**: 一款 Python 语言基于FastAPI、VUE、MySQL等框架的TMS系统，采用模块化、高性能、企业级的敏捷开发框架，本着简化开发、提升开发效率的初衷触发，框架自研了一套个性化、轻量级的组件，是一款真正意义上实现组件化开发的敏捷开发框架。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-11-02
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TMS 运输管理系统 (FastAPI 版)
![DOCS](https://img.shields.io/badge/%E6%96%87%E6%A1%A3-%E5%9C%A8%E7%BA%BF-green.svg?logo=readthedocs&label=Docs)
![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-green.svg)
![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0+-orange.svg)
![Redis](https://img.shields.io/badge/Redis-1.104+-red.svg)
![License](https://img.shields.io/badge/License-MIT-lightgrey.svg)

## 一、项目介绍
### 1.1 项目背景
TMS（Transportation Management System）运输管理系统是面向物流企业/企业物流部门的核心业务系统，聚焦解决**订单管理、运输调度、轨迹追踪、客户管理、报表统计**等核心物流业务场景，通过标准化接口和高效的后端逻辑，提升物流运输效率、降低管理成本。

### 1.2 核心特性
- ✅ **高性能**：基于 FastAPI + Orjson 实现高性能接口，支持高并发请求；
- ✅ **模块化设计**：按业务领域拆分模块（订单、运输、客户、认证等），易扩展、易维护；
- ✅ **环境隔离**：支持开发/生产环境配置分离，适配不同部署场景；
- ✅ **统一规范**：统一响应格式、全局异常处理、链路追踪，符合企业级开发规范；
- ✅ **完整生态**：集成 JWT 认证、数据库迁移、接口文档自动生成、单元测试等核心能力；
- ✅ **业务适配**：深度适配物流运输场景（运单管理、车辆调度、轨迹上报、运费结算等）。

### 1.3 技术栈
| 分类 | 核心技术 | 作用 |
|------|----------|------|
| 后端框架 | FastAPI | 高性能异步 Web 框架，自动生成 OpenAPI 文档 |
| 数据库 | MySQL + SQLAlchemy 2.0 | 关系型数据库 + ORM 框架，管理业务数据 |
| 数据库迁移 | Alembic | 管理数据库表结构变更（版本控制） |
| 认证授权 | JWT + Passlib | 用户登录认证、权限控制 |
| 序列化 | Orjson | 高性能 JSON 序列化（比内置 json 快 5-10 倍） |
| 配置管理 | python-dotenv | 环境变量管理，支持多环境配置 |
| 部署运行 | Uvicorn | ASGI 服务器，支持异步运行 |

<img alt="技术架构图.jpg" src="doc%2F%E6%8A%80%E6%9C%AF%E6%9E%B6%E6%9E%84%E5%9B%BE.jpg" width="683px"/>

### 1.4 适用场景
- 中小物流企业的运输业务管理；
- 企业内部物流部门的运单/车辆管理；
- 物流 SaaS 平台的核心后端服务；
- 学习 FastAPI 企业级项目开发的参考模板。

<img alt="结构图.jpg" src="doc%2F%E7%BB%93%E6%9E%84%E5%9B%BE.jpg" width="683px"/>

## 二、环境准备
### 2.1 基础环境要求
| 依赖 | 版本要求 | 备注 |
|------|----------|------|
| Python | 3.8+ | 推荐 3.9/3.10（兼容性最佳） |
| MySQL | 5.7+/8.0+ | 关系型数据库，存储业务数据 |
| Redis（可选） | 5.0+ | 缓存运输轨迹、JWT 令牌等 |

### 2.2 依赖安装
```bash
# 克隆项目（本地开发可跳过，直接使用本地目录）
git clone https://gitee.com/zhiops/xetms-fastapi.git
cd xetms-fastapi

# 第一种方法：miniconda安装
# 下载或部署环境
https://www.python.org/downloads/
或用Miniconda
https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe

# 创建名为test_env的Python 3.9虚拟环境
 conda create -n xetms python=3.9

# 示例命令行操作
 conda create -n xetms python=3.9

# 如果需要同时安装一些基础包，可以这样写：本项目用requirenments安装基础包
 conda create -n xetms python=3.9 numpy pandas matplotlib

# 激活环境
 conda activate xetms

# 退出环境
 conda deactivate

# 删除环境
 conda remove -n xetms --all


# 第二种方法： virtual environment‌（虚拟环境）
# 克隆项目（本地开发可跳过，直接使用本地目录）
git clone https://gitee.com/zhiops/xetms-fastapi.git
cd xetms-fastapi

# 创建虚拟环境（推荐）
python -m venv venv
# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

## 三、快速启动
### 3.1 配置文件修改
项目根目录下提供了 `.env.dev`（开发环境）和 `.env.prod`（生产环境）配置文件，需根据本地环境修改核心配置：

#### 开发环境配置（.env.dev）
```ini
# 环境标识
APP_ENV=dev
IS_DEV=true
LOG_LEVEL=DEBUG

# FastAPI 配置
FASTAPI_ROOT_PATH=/dev-api
FASTAPI_DOCS_URL=/docs
FASTAPI_OPENAPI_URL=/openapi.json

# 数据库配置（替换为本地 MySQL 地址/账号/密码）
DB_URL=mysql+pymysql://root:123456@localhost:3306/tms_dev
DB_ECHO=true

# JWT 配置（生产环境请修改为随机强密钥）
JWT_SECRET_KEY=dev_secret_key_tms_2026_02
JWT_EXPIRE_MINUTES=120

# 主数据库配置
# 数据库主机
DB_MASTER_HOST = '192.168.40.32'
# 数据库端口
DB_MASTER_PORT = 3307
# 数据库用户名
DB_MASTER_USERNAME = 'root'
# 数据库密码
DB_MASTER_PASSWORD = 'welcome123!'
# 数据库名称
DB_MASTER_DATABASE = 'xetms'
# 是否开启sqlalchemy日志
DB_MASTER_ECHO = true
# 数据库自动检测失效连接
DB_MASTER_POOL_PRE_PING = true
# 允许溢出连接池大小的最大连接数
DB_MASTER_MAX_OVERFLOW = 10
# 连接池大小，0表示连接数无限制
DB_MASTER_POOL_SIZE = 50
# 连接回收时间（单位：秒）
DB_MASTER_POOL_RECYCLE = 3600
# 连接池中没有线程可用时，最多等待的时间（单位：秒）
DB_MASTER_POOL_TIMEOUT = 30

```

### 3.2 数据库初始化
```bash
# 1. 创建数据库（手动执行 SQL 或通过 MySQL 客户端）
mysql -u root -p
> CREATE DATABASE IF NOT EXISTS tms_dev DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 2. 初始化 Alembic（首次使用）
alembic init migrations

# 3. 修改 alembic.ini 中的数据库连接（指向 tms_dev）
# sqlalchemy.url = mysql+pymysql://root:123456@localhost:3306/tms_dev

# 4. 生成迁移文件（根据模型创建表结构）
alembic revision --autogenerate -m "init tms tables"

# 5. 执行迁移（创建表）
alembic upgrade head
```

### 3.3 启动项目
```bash
# 开发环境（支持热重载）
python main.py

# 或直接使用 uvicorn 启动
uvicorn main:app --host 0.0.0.0 --port 8000 --reload --root-path /dev-api

# 生产环境（禁用热重载，指定生产配置）
APP_ENV=prod uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```

### 3.4 验证启动成功
1. 访问健康检查接口：`http://localhost:8000/dev-api/api/health`  
   成功返回：
   ```json
   {
     "status": "ok",
     "env": "dev",
     "service": "TMS"
   }
   ```
2. 访问接口文档：`http://localhost:8000/dev-api/docs`  
   可查看所有接口的 Swagger UI 文档，支持在线调试。

## 四、核心功能模块
| 模块 | 接口前缀 | 核心功能 | 适用角色 |
|------|----------|----------|----------|
| 认证授权 | `/api/auth` | 登录、注销、刷新 Token、权限校验 | 所有用户（司机/管理员） |
| 订单管理 | `/api/order` | 运单创建、查询、修改、删除、状态更新 | 管理员/客服 |
| 运输管理 | `/api/transport` | 车辆调度、司机派单、轨迹上报、签收确认 | 调度员/司机 |
| 客户管理 | `/api/customer` | 发货方/收货方信息增删改查、地址维护 | 管理员/客服 |
| 报表统计 | `/api/report` | 订单量统计、运输时效统计、运费结算报表 | 管理员/财务 |
| 健康检查 | `/api/health` | 服务状态监控 | 运维/网关 |

### 4.1 核心接口示例
#### 1. 登录接口
- 路径：`POST /api/auth/login`
- 请求体：
  ```json
  {
    "username": "admin",
    "password": "123456"
  }
  ```
- 响应：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "token_type": "bearer",
      "expire_at": "2026-02-27T18:00:00+00:00"
    },
    "success": true,
    "time": "2026-02-27T16:00:00+00:00"
  }
  ```

#### 2. 创建订单接口
- 路径：`POST /api/order`
- 请求头：`Authorization: Bearer {token}`
- 请求体：
  ```json
  {
    "order_no": "TMS20260227001",
    "customer_id": 1,
    "transport_type": "整车",
    "start_address": "北京市朝阳区XX路XX号",
    "end_address": "上海市浦东新区XX路XX号",
    "goods_name": "电子产品",
    "goods_weight": 5000,
    "freight": 2000
  }
  ```
- 响应：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "id": 1,
      "order_no": "TMS20260227001",
      "status": "待分配",
      "create_time": "2026-02-27T16:05:00+00:00"
    },
    "success": true,
    "time": "2026-02-27T16:05:00+00:00"
  }
  ```

## 五、项目目录结构
```
FastTms/
├── apps/                      # 应用模块目录
│   └── system/               # 系统管理模块
│       ├── api/v1/          # API 接口层
│       ├── controller/      # 控制器层（21 个文件）
│       ├── crud/           # 数据访问层（19 个文件）
│       ├── models/         # 数据模型层（15 个文件）
│       ├── schemas/        # Pydantic 模式（18 个文件）
│       └── services/       # 业务逻辑层（21 个文件）
├── core/                    # 核心配置与工具
│   ├── annotation/         # 装饰器注解
│   ├── aspect/            # AOP 切面
│   ├── middlewares/       # 中间件
│   ├── mounts/            # 挂载应用
│   ├── base_model.py      # 基础模型
│   ├── database.py        # 数据库连接
│   ├── engine.py          # 数据库引擎
│   ├── get_db.py          # 数据库工具
│   ├── get_redis.py       # Redis 工具
│   └── get_scheduler.py   # 定时任务调度器
├── sql/                     # 数据库 SQL 脚本（6 个文件）
├── templates/web-ui/       # Vue 前端项目
├── utils/                  # 通用工具类（20+ 文件）
├── task/                   # 后台任务
├── script/                 # 脚本工具
└── logs/                   # 日志目录
```

### 目录核心说明
| 目录/文件 | 核心职责 |
|-----------|----------|
| `apps/` | 业务模块核心，按「路由-校验-服务-模型」分层，低耦合、高内聚 |
| `config/` | 配置管理，加载多环境变量，提供数据库连接配置 |
| `core/` | 框架基础能力，包含全局异常处理、中间件、统一响应工具 |
| `migrations/` | 数据库版本控制，管理表结构变更 |
| `main.py` | 项目入口，初始化 FastAPI 实例、注册路由/中间件 |

## 六、部署说明
### 6.1 生产环境部署（Docker 方式，推荐）
#### 1. 编写 Dockerfile
```dockerfile
FROM python:3.10-slim

WORKDIR /app

# 安装依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 复制项目文件
COPY . .

# 设置环境变量
ENV APP_ENV=prod
ENV PYTHONUNBUFFERED=1

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]
```

#### 2. 编写 docker-compose.yml
```yaml
version: '3.8'

services:
  tms-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - APP_ENV=prod
      - DB_URL=mysql+pymysql://root:prod123@mysql:3306/tms_prod
      - JWT_SECRET_KEY=prod_secret_key_tms_2026_02
    depends_on:
      - mysql
    restart: always

  mysql:
    image: mysql:8.0
    ports:
      - "3306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=prod123
      - MYSQL_DATABASE=tms_prod
    volumes:
      - mysql-data:/var/lib/mysql
    restart: always

volumes:
  mysql-data:
```

#### 3. 启动容器
```bash
docker-compose up -d
```

### 6.2 生产环境注意事项
1. **安全配置**：
   - 修改 JWT 密钥为随机强密钥（推荐使用 `openssl rand -hex 32` 生成）；
   - 限制数据库访问 IP，仅允许应用服务器连接；
   - 禁用 Swagger 文档（`.env.prod` 中设置 `FASTAPI_DOCS_URL=None`）；
2. **性能优化**：
   - 使用 `workers` 参数启动多进程（推荐数量 = CPU 核心数 * 2 + 1）；
   - 开启数据库连接池，优化 SQLAlchemy 连接配置；
   - 核心接口（如轨迹查询）添加 Redis 缓存；
3. **监控运维**：
   - 集成 Prometheus + Grafana 监控服务状态；
   - 配置日志轮转，避免日志文件过大；
   - 新增接口访问日志，便于问题排查。

## 七、开发规范
### 7.1 代码规范
- 遵循 PEP 8 编码规范，使用 `black` 格式化代码；
- 所有接口参数/响应使用 Pydantic 校验，确保类型安全；
- 业务逻辑写在 `service.py` 中，路由仅负责接收请求/返回响应；
- 自定义异常统一继承 `BaseException`，并在 `core/exceptions.py` 中注册处理器。

### 7.2 提交规范
```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```
- type：feat（新功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、test（测试）、chore（构建）；
- scope：模块名（如 order/transport/customer）；
- subject：简短描述（不超过 50 字符）。

示例：
```
feat(order): 新增订单状态变更接口
- 支持订单从「待分配」改为「运输中」
- 增加状态变更日志记录
```

## 八、常见问题
### 8.1 接口文档加载失败（404 /dev-api/openapi.json）
- 检查 `FASTAPI_ROOT_PATH` 配置是否与启动参数 `--root-path` 一致；
- 确认 `FASTAPI_OPENAPI_URL` 未被设置为 `None`；
- 若使用反向代理（Nginx），需添加 `X-Forwarded-Prefix` 头。

### 8.2 数据库连接失败
- 检查 `DB_URL` 中的账号/密码/地址是否正确；
- 确认 MySQL 服务已启动，且允许远程连接；
- 检查防火墙是否放行 3306 端口。

### 8.3 接口返回 500 错误
- 开发环境查看控制台日志，生产环境查看日志文件；
- 确认自定义异常已注册到全局异常处理器；
- 检查数据库表结构是否与模型一致（执行 `alembic upgrade head` 同步）。

## 九、扩展开发
### 9.1 新增业务模块
以「运费结算」模块为例：
1. 在 `apps/` 下创建 `settlement/` 目录，包含 `router.py`/`schema.py`/`service.py`/`models.py`；
2. 定义结算相关数据库模型（如 `Settlement`）；
3. 编写 Pydantic 校验模型（入参/出参）；
4. 实现结算业务逻辑（如运费计算、对账）；
5. 注册路由到 `main.py`：`app.include_router(settlement_router, prefix="/api/settlement", tags=["运费结算"])`。

### 9.2 集成第三方服务
- **短信通知**：集成阿里云/腾讯云短信 SDK，在 `apps/notify/` 模块实现订单状态推送；
- **GPS 轨迹**：对接 GPS 设备厂商 API，实时上报车辆位置到 `apps/transport/` 模块；
- **PDF 导出**：使用 `reportlab` 生成运单 PDF，存储到 `static/` 目录。

## 十、许可证
本项目基于 MIT 许可证开源，可自由修改、分发，商用需保留版权声明。

## 十一、联系方式
- 维护者：Your Name
- 邮箱：your-email@example.com
- 问题反馈：[GitHub Issues](https://github.com/your-name/tms-project/issues)

---

## 补充说明
1. 可根据实际项目情况修改「联系方式」「许可证」「第三方集成」等章节；
2. 若项目无需 Docker 部署，可删除「6.1 生产环境部署（Docker 方式）」章节，补充传统部署（如 Supervisor 管理进程）；
3. 随着项目迭代，可在「核心功能模块」「常见问题」章节补充更多内容；
4. 建议将 `README.md` 中的示例接口、配置信息替换为项目实际内容，确保文档与代码一致。