# 交通统计报表审核系统 — 打包与部署说明

> 适用：main 分支（最新更新 2026-09-13）。后端 Spring Boot 2.7（Java 8），前端 Vue 2 + Element UI。
> 本文档面向开发与部署同事，命令均在 Windows 下验证。

## 一、项目结构

| 目录 | 说明 |
|------|------|
| `traffic-audit-server` | 后端（Spring Boot，Java 8，端口 8090，接口全部在 `/api/**`） |
| `traffic-audit-web` | 前端（Vue 2 + Element UI，开发端口 8080，`/api` 代理到 8090） |
| `docs` | 运行数据目录（报表模板、汇总大表母版等），**发布必须带上** |
| `package-deploy.py` | 一键打包脚本（前端构建 → 内嵌进 jar → 组装部署包 → 打 zip） |

## 二、环境要求

| 组件 | 版本 | 说明 |
|------|------|------|
| JDK | 1.8 | 部署机必须；后端编译/运行 |
| MySQL | 5.7 / 8.0 | 部署机必须，库名 `traffic_audit` |
| Maven 3.x / Node.js 14+ | — | **只有「在部署机上打包」才需要**；用一键脚本产出的包部署则不需要 |
| Redis | **不需要** | 代码未使用 Redis（旧说明中的 Redis 配置是遗留项，可忽略） |
| nginx / IIS | **不需要** | 前端已内嵌进 jar，访问 8090 即可；要前后端分离时才是备选 |

## 三、打包（在开发机上执行，推荐一键脚本）

```powershell
cd D:\文档\ChatGPT\traffic-audit
python package-deploy.py            # 全流程：前端构建 + 后端打包 + 组装 + 压缩
python package-deploy.py --no-build # 跳过前端构建（dist 已是最新时更快）
```

脚本做了什么：

1. `traffic-audit-web` 下 `npm run build` → `dist`；
2. 把 `dist` 复制进 `traffic-audit-server/src/main/resources/static`，使 **jar 自带前端**，再 `mvn clean package -DskipTests`（跑完自动清空 static，保持仓库干净）；
3. 组装 `deploy/traffic-audit-deploy-YYYYMMDD/`；
4. 压缩为 `traffic-audit-deploy-YYYYMMDD.zip`（约 70 MB）。

手工等价命令（不想用脚本时）：

```powershell
cd traffic-audit-web ; npm run build ; cd ..
robocopy traffic-audit-web\dist traffic-audit-server\src\main\resources\static /E
cmd /c "mvn -q clean package -DskipTests -f traffic-audit-server\pom.xml"
```

> 注意：手工方式跑完记得删掉 `traffic-audit-server/src/main/resources/static` 下的内容，否则会污染源码目录。

## 四、部署包内容

```
traffic-audit-deploy-YYYYMMDD/
├─ backend/
│  ├─ traffic-audit-server-1.0.0-SNAPSHOT.jar   后端 + 内嵌前端（约 55 MB）
│  ├─ docs/                                     模板与运行数据（必需，勿删）
│  ├─ application.yml                           外部配置（改这里即可，无需重打包）
│  └─ start-backend.cmd / start-backend.sh       启动脚本
├─ frontend/
│  ├─ dist/                                     前端产物（仅 nginx 方案需要）
│  └─ nginx.conf.example                         nginx 配置示例
├─ db/
│  ├─ init.sql                                  建库建表 + 预置账号（必须执行）
│  ├─ sql_city_bus.sql                          城市客运-公交月度表（必须执行）
│  ├─ sql_city_taxi.sql                         城市客运-出租月度表/授权表（必须执行）
│  └─ sql_wyc.sql                               网约车全省总量/订单分市州表（必须执行）
└─ README-部署说明.txt
```

## 五、目标机器部署步骤

### 5.1 初始化数据库（4 个脚本都要执行）

```bash
mysql --default-character-set=utf8mb4 -u root -p < db/init.sql
mysql --default-character-set=utf8mb4 -u root -p traffic_audit < db/sql_city_bus.sql
mysql --default-character-set=utf8mb4 -u root -p traffic_audit < db/sql_city_taxi.sql
mysql --default-character-set=utf8mb4 -u root -p traffic_audit < db/sql_wyc.sql
```

- 预置账号：`admin / admin123`（登录后请立即改密码）。
- 想连数据一起搬：在源机器 `mysqldump -u root -p --databases traffic_audit > traffic_audit_full.sql`，在目标机器 `mysql -u root -p < traffic_audit_full.sql`（会覆盖预置账号）。

### 5.2 改配置 `backend/application.yml`

| 配置项 | 说明 |
|--------|------|
| `spring.datasource.url` | 数据库地址（出厂值 `127.0.0.1:3306/traffic_audit`，按实际改） |
| `spring.datasource.username/password` | 数据库账号密码（**必改**） |
| `jwt.secret` | 登录令牌密钥；**必须是 Base64 合法字符且长度是 4 的倍数**（出厂值是一串 32 位十六进制）；填中文或非法字符会导致登录 500（程序已做兜底并打 WARN，但仍建议填规范值） |
| `deepseek.api-key` | AI 分析用，不用可留空 |
| `server.port` | 默认 8090 |

> 外置 `application.yml` 与 jar 同级即生效（优先级高于 jar 内置配置），改完不用重新打包。

### 5.3 启动（必须在 `backend` 目录下）

```powershell
# Windows：双击 start-backend.cmd；或
cd backend ; java -jar traffic-audit-server-1.0.0-SNAPSHOT.jar
```

```bash
# Linux
cd backend && sh start-backend.sh
```

成功标志：日志出现 `Started TrafficAuditApplication` 与 `Tomcat started on port(s): 8090`。

### 5.4 访问

浏览器打开 `http://<部署机IP>:8090`（前端已内嵌，页面与接口同源，无需 nginx），账号 `admin / admin123`。

## 六、关键配置（application.yml）与运行数据

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `docs.template-root` | `docs` | 导入模板下载根目录 |
| `city-passenger.template-dir` | `docs/城市客运` | 城市客运（含《模板_网约车订单.docx》） |
| `passenger.template-dir` | `docs/公路旅客` | 公路旅客 |
| `freight.template-dir` | `docs/货运` | 货运 |
| `energy.template-dir` | `docs/能耗` | 能耗 |
| `investment.template-dir` | `docs/投资/模板` | 投资 |
| `summary.template-dir` | `docs/生成汇总大表` | **汇总大表母版与版式参照件**（导出报表依赖） |

`docs/生成汇总大表` 至少要有：

- `生成_道路运输量汇总表.xlsx`（版式参照件，缺失会退回默认列宽）；
- 需要导出的各月份母版 `YYYY年M月道路运输量汇总表.xlsx`（缺哪个月，导那个月就会明确报错）。

## 七、前端部署（两种方式）

1. **推荐：jar 内嵌**——一键脚本已把 `dist` 打进 jar，直接访问 `http://<IP>:8090` 即可，无需额外 Web 服务器。
2. 备选：nginx 托管 `frontend/dist` 并把 `/api` 反代到 8090（配置见 `frontend/nginx.conf.example`）；上传 100MB 大文件时记得设 `client_max_body_size 100m`。

前端路由为 hash 模式，刷新/直达不会 404。

## 八、部署后验证清单

1. `http://<IP>:8090` 打开登录页（页面不是空白）；
2. `admin / admin123` 能登录，左上角显示「管理员」；
3. 「数据导入」页能下载模板、能上传 Excel；
4. 「报表」页查询 + 导出《道路运输量汇总表》，能下载到 xlsx；
5. 打开导出的 xlsx，核对当月数值是否为最新报表期。

## 九、常见问题

| 现象 | 原因 / 处理 |
|------|------------|
| 启动报「未找到数据目录 docs」 | 必须在 `backend` 目录下启动（jar 与 docs 同级） |
| 导出报「未找到模板文件 xxx」 | `docs` 对应子目录缺模板；从源机器拷贝 |
| 导出报「未找到汇总表母版《YYYY年M月…》」 | `docs/生成汇总大表` 缺该月母版 |
| 登录接口 500 | `jwt.secret` 填了非法字符（如中文）；改成 32 位十六进制串 |
| 页面能开但接口 404 | 走 nginx 方案时没配 `/api` 反代；改用 jar 内嵌访问 8090 |
| 数据库连接失败 | 检查 `application.yml`；确认 4 个 SQL 脚本已执行 |
| 端口占用 | 改 `server.port`；前端开发端口 8080 |

## 十、开发环境日常启动

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1
```

后端 8090（`mvn spring-boot:run`）+ 前端 8080（`npm run serve`），访问 `http://localhost:8080`。

## 十一、变更记录

- **2026-09-13**：新增一键打包脚本 `package-deploy.py`；jar 改为内嵌前端（部署机不再需要 nginx）；删除 Redis 相关说明（代码未使用）；补 `sql_wyc.sql` 与 `summary.template-dir`；补 `jwt.secret` 取值规则；补部署后验证清单。
- 2026-08-27：首版（zip 部署包 + nginx 方案）。