# qms

**Repository Path**: bukcn/qms

## Basic Information

- **Project Name**: qms
- **Description**: Travel Management System
- **Primary Language**: Java
- **License**: GPL-3.0
- **Default Branch**: tms-java21
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-11-19
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: buk-cn

## README

# TMS 差旅管理系统

> **版本**: 2.0.0 | **语言**: Java 21 | **框架**: Spring Boot 4.0.6 | **ORM**: Hibernate 7.2 (JPA 3)

企业商旅管理（TMC）平台，提供机票预订、酒店查询、订单管理、支付结算、报表统计等综合商旅服务。

## License

本项目基于 **GNU General Public License v3.0 (GPL v3)** 开源，详见 [LICENSE](LICENSE) 文件。

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Java 21（虚拟线程已启用） |
| 框架 | Spring Boot 4.0.6 |
| 安全 | Spring Security + BCryptPasswordEncoder |
| ORM | Hibernate 7.2 (JPA 3) + Hibernate Envers |
| 数据库 | MySQL 8（多数据源: qms + flight） |
| 缓存 | Redis（Jedis + Spring Data Redis） |
| 消息 | ActiveMQ (JMS) |
| 分布式锁 | ShedLock + Redis |
| API 文档 | SpringDoc OpenAPI 3.0 |
| 构建 | Maven（多模块，JaCoCo 覆盖率） |
| 打包 | WAR（支持 JSP，embedded Tomcat） |

## 项目模块

```
qms/
├── qms-jedis           # Redis 缓存服务
├── qms-dao             # 数据访问层（实体 + DAO）
├── qms-flight-dao      # 航班数据访问层
├── qms-service         # 业务逻辑层
├── qms-flight-service  # 航班业务服务
├── qms-alert-service   # 告警通知服务
└── qms-bijia-webapp    # Web 应用（主入口）
```

## 环境要求

- JDK 21+
- Maven 3.8+
- MySQL 8.0+
- Redis

## 快速开始

### 1. 克隆代码

```bash
git clone <repository-url>
cd qms
```

### 2. 配置环境变量

```bash
cp env.properties.example .env
```

编辑 `.env` 文件，填入实际的数据库连接信息和服务地址。

### 3. 构建项目

```bash
# 全量构建（跳过测试，加快构建速度）
mvn clean package -Dmaven.test.skip=true
```

构建产物：`qms-bijia-webapp/target/qms.war`

### 4. 启动应用

**方式一：使用启动脚本（推荐）**

脚本会自动加载 `.env` 环境变量：

```bash
./start.sh
```

**方式二：直接运行**

```bash
# 先加载环境变量
source .env
# 启动应用
export JAVA_HOME=/path/to/jdk-21   # 请替换为本地 JDK 路径
java -jar qms-bijia-webapp/target/qms.war
```

## Docker 部署

提供两个 Docker Compose 文件，支持本地 MySQL 和外部 MySQL 两种部署方式。

### 文件说明

| 文件 | 适用场景 |
|------|----------|
| `docker-compose.yml` | 本地 MySQL（单机全量部署） |
| `docker-compose.external.yml` | 外部 MySQL（仅部署 Redis + 应用） |

### 快速启动

```bash
# 本地 MySQL 版（推荐）
docker compose up -d

# 外部 MySQL 版（需通过 .env 配置 DB_HOST 等）
docker compose -f docker-compose.external.yml up -d
```

### 环境变量

复制环境变量模板并编辑：

```bash
cp env.properties.example .env
```

`.env` 文件和 `.yml` 文件放在同一目录即可，Docker Compose 会自动加载。

关键变量说明：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `DB_HOST` | `mysql` | MySQL 地址（外部版需改为实际 IP） |
| `DB_PORT` | `3306` | MySQL 端口 |
| `DB_NAME` | `buk` | 数据库名 |
| `DB_USERNAME` | `root` | 数据库用户名 |
| `MYSQL_PASSWORD` | 随机生成 | 数据库密码 |
| `REDIS_PASSWORD` | 随机生成 | Redis 密码 |
| `DEMO_MODE` | `false` | 演示模式 |

> 密码已有安全默认值，也可在 `.env` 中覆盖。

### 数据目录

启动后会在当前目录自动创建以下目录：

| 目录 | 内容 |
|------|------|
| `data/mysql/` | MySQL 数据库文件 |
| `data/redis/` | Redis 持久化数据 |
| `logs/` | 应用日志 |

### 首次部署 — 初始化数据库

`spring.jpa.hibernate.ddl-auto` 设为 `validate`，Hibernate 不会自动建表，需手动执行 SQL 初始化：

```bash
# 等待 MySQL 就绪后，进入容器执行
docker exec -i tms-mysql mysql -uroot -p'<密码>' buk < doc/sql/seed/init_data.sql
docker exec -i tms-mysql mysql -uroot -p'<密码>' buk < doc/sql/seed/sys_privileges.sql

# 基础字典
docker exec -i tms-mysql mysql -uroot -p'<密码>' buk < doc/sql/seed/basic/<文件名>.sql
```

### 停止

```bash
docker compose down
docker compose -f docker-compose.external.yml down
```

---

## 主要优化成果

| 类别 | 项目 | 状态 |
|------|------|:----:|
| 🔒 安全 | MD5 密码 → BCrypt（双模式兼容，渐进升级） | ✅ |
| 📦 超大文件 | 9 个文件拆分（最长 3628→1371 行） | ✅ |
| 🧹 代码规范 | `System.out`/`e.printStackTrace` 全部清除 | ✅ |
| 🔄 Switch | 10 个文件 13 处传统 switch → Switch 表达式 | ✅ |
| 🔒 线程安全 | `HashMap`→`ConcurrentHashMap`、`@Async` 异常处理器 | ✅ |
| ⚙️ 配置 | context-path `/api/v1`、ActiveMQ 环境变量化 | ✅ |
| 🚀 Java 21 | 虚拟线程、`instanceof` 模式匹配、Record、`List.of()` | ✅ |
| 📐 架构 | ShedLock 分布式锁、SpringDoc OpenAPI、JaCoCo | ✅ |
| 🏷️ 版本 | 2.0.0-SNAPSHOT → **2.0.0 正式版** | ✅ |

详情参见 [优化建议 v9](doc/项目优化建议-v8.md)。

### 已移除的外部依赖

| 模块 | 说明 |
|------|------|
| 南航 NDC 接口 | 移除 CZ NDC 自动出票、退改签、订单状态同步及相关 API |
| 深圳科技 SZKJ-ETERM | 移除 SZKJ 接口依赖、ETERM 自动出票及 PNR 详情获取 |
| ETERM 指令通道 | 移除 qms-flight-service 中 eterm 客户端及指令执行能力 |
| 企业微信集成 | 移除企微消息推送、用户同步、登录绑定等功能 |
| JSP 视图 | 移除 JSP 页面及视图解析器配置（纯 REST API） |

## 环境变量说明

| 变量名 | 说明 |
|--------|------|
| `DB_HOST` | MySQL 主机地址 |
| `DB_PORT` | MySQL 端口 |
| `DB_NAME` | 主数据库名 |
| `DB_USERNAME` | 数据库用户名 |
| `DB_PASSWORD` | 数据库密码 |
| `URL_TMS_WEIXIN_SERVICE` | 微信服务地址 |
| `URL_TMS_WORKWX_SERVICE` | 企业微信服务地址 |
| `API_FLIGHT_URL` | 航班 API 地址 |
| `API_HOTEL_URL` | 酒店 API 地址 |

## 文档

- [项目分析文档](doc/项目分析文档.md) — 全面分析
- [升级计划](doc/升级计划-SpringBoot4.0.6-Java21-MySQL8.md) — Spring Boot 4.0.6 + Java 21 升级方案
- [优化建议 v9](doc/项目优化建议-v8.md) — 最新优化分析报告（当前版本）
- [优化历史 v7](doc/项目优化建议-v7.md) — 上一版本优化成果
- [项目实体关系](doc/项目实体关系.md) — 数据模型说明
- [优化工作清单](todo) — 待处理的优化任务列表