# 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**: 1 - **Forks**: 0 - **Created**: 2025-11-02 - **Last Updated**: 2026-03-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # TMS 运输管理系统 (FastAPI 版) ![Python](https://img.shields.io/badge/Python-3.8+-blue.svg) ![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 服务器，支持异步运行 | ### 1.4 适用场景 - 中小物流企业的运输业务管理； - 企业内部物流部门的运单/车辆管理； - 物流 SaaS 平台的核心后端服务； - 学习 FastAPI 企业级项目开发的参考模板。 ## 二、环境准备 ### 2.1 基础环境要求 | 依赖 | 版本要求 | 备注 | |------|----------|------| | Python | 3.8+ | 推荐 3.9/3.10（兼容性最佳） | | MySQL | 5.7+/8.0+ | 关系型数据库，存储业务数据 | | Redis（可选） | 5.0+ | 缓存运输轨迹、JWT 令牌等 | ### 2.2 依赖安装 ```bash # 克隆项目（本地开发可跳过，直接使用本地目录） git clone https://github.com/your-name/tms-project.git cd tms-project # 创建虚拟环境（推荐） 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 ``` ### 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 提交规范 ``` ():