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

> 适用：合并后 main 分支（2026-08-27 起）。后端 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` | 运行数据目录（报表 Word/Excel 模板 + 目录导入数据），**发布必须带上** |
| `docs/init.sql` | 数据库初始化脚本（建库建表 + 初始账号） |

## 二、环境要求

| 组件 | 版本 | 用途 |
|------|------|------|
| JDK | 1.8 | 后端编译与运行 |
| Maven | 3.x | 后端打包 |
| Node.js | 14+ | 前端打包（vue-cli 4.5） |
| MySQL | 8.0 | 数据库（库名 `traffic_audit`） |

## 三、数据库初始化

先执行建库建表脚本，再按需导入城市客运数据：

```bash
mysql --default-character-set=utf8mb4 -h <主机> -P 3306 -u root -p < docs/init.sql
mysql --default-character-set=utf8mb4 -h <主机> -P 3306 -u root -p traffic_audit < docs/sql_city_bus.sql
mysql --default-character-set=utf8mb4 -h <主机> -P 3306 -u root -p traffic_audit < docs/sql_city_taxi.sql
```

- `init.sql` 会重建 `traffic_audit` 库并预置初始账号：`admin / admin123`（生产环境请登录后改密码）
- `sql_city_bus.sql`、`sql_city_taxi.sql` 为城市客运（公交/出租）示例数据，按需导入

## 四、打包

### 4.1 后端（项目根目录执行）

```powershell
cmd /c "mvn -q clean package -DskipTests -f traffic-audit-server\pom.xml"
```

产物：`traffic-audit-server\target\traffic-audit-server-1.0.0-SNAPSHOT.jar`（可执行 fat jar，约 57MB）。

### 4.2 前端（`traffic-audit-web` 目录执行）

```powershell
cd traffic-audit-web
npm run build
```

产物：`traffic-audit-web\dist\`（`index.html` + `css/js/fonts`，纯静态文件）。

## 五、部署目录结构（推荐）

```
deploy\
├─ app.jar                    # 后端 jar（可改名）
├─ docs\                      # 必须：模板与目录导入数据目录
│  ├─ 城市客运\
│  ├─ 公路旅客\
│  ├─ 货运\
│  ├─ 能耗\
│  ├─ 投资\
│  │  └─ 模板\
│  └─ (6月\ 7月\ 等导入数据目录，按需)
└─ web\                       # 前端 dist 的内容
   ├─ index.html
   ├─ css\  js\  fonts\
```

关键点：

- **`docs` 必须放在 jar 同级**。后端运行时按启动目录向上查找 `docs`（报表导出的 Word 模板、导入页「下载模板」、目录导入数据都从这里读），找不到会报「未找到数据目录 docs」或「未找到模板文件 xxx」。
- 首次部署直接把项目里的整个 `docs` 拷过去最稳妥；后续可精简（只留模板子目录），详见「常见问题」。
- `application.yml` 打包在 jar 内；部署机需要改配置时，可在 jar 同级放一个外置 `application.yml`（外置优先级高于内置），或改完再打包。

## 六、关键配置（application.yml）

| 配置项 | 说明 |
|--------|------|
| `spring.datasource.url/username/password` | 数据库连接（模板默认 `localhost:3305/root/root`，部署机**必须改**；生产建议用环境变量 `MYSQL_PASSWORD` 注入） |
| `deepseek.api-key` | AI 分析接口密钥（环境变量 `DEEPSEEK_API_KEY`，不使用 AI 分析可留空） |
| `jwt.secret` | 登录令牌密钥（生产必须改，环境变量 `JWT_SECRET`） |
| `docs.template-root` | 导入模板下载根目录（默认 `docs`） |
| `city-passenger.template-dir` | 城市客运报表模板目录（默认 `docs/城市客运`） |
| `passenger.template-dir` | 公路旅客报表模板目录（默认 `docs/公路旅客`） |
| `freight.template-dir` | 货运报表模板目录（默认 `docs/货运`） |
| `energy.template-dir` | 能耗报表模板目录（默认 `docs/能耗`） |
| `investment.template-dir` | 投资报表模板目录（默认 `docs/投资/模板`） |

> 注意：仓库只提交占位模板 `application.yml.example`，真实 `application.yml` 不入库。

## 七、启动后端

```powershell
cd deploy
java -jar app.jar
```

- 成功标志：日志出现 `Started TrafficAuditApplication` 和 `Tomcat started on port(s): 8090`。
- 在 `deploy` 目录下启动即可命中同级的 `docs`。

## 八、前端部署（nginx 示例）

`dist` 是纯静态文件，需要 Web 服务器托管；前端接口走相对路径 `/api`，**必须反代到后端 8090**：

```nginx
server {
    listen 80;
    server_name _;
    root D:/deploy/web;            # 前端 dist 目录
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;   # 路由为 hash 模式，此行保留以防后续改 history
    }

    location /api {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    client_max_body_size 100m;     # 上传 Excel 需要，与后端 multipart 100MB 对齐
}
```

## 九、部署后验证

1. 浏览器打开 `http://<服务器>/`；
2. 用 `admin / admin123` 登录（生产改密后使用新密码）；
3. 数据导入：下载模板 → 上传 Excel（或目录导入）；
4. 报表：查询 → 预览/导出（依赖 `docs` 模板文件）；
5. AI 分析：需配置 `deepseek.api-key` 后可用。

## 十、常见问题

| 现象 | 原因 / 处理 |
|------|------------|
| 启动报「未找到数据目录 docs」 | 当前运行目录不对；把 `docs` 放到 jar 同级再启动 |
| 导出报「未找到模板文件 xxx」 | `docs` 对应子目录缺模板文件；首次部署拷整个 `docs` |
| 页面能开但接口 502/404 | nginx 没配 `/api` 反代，或后端没启动成功 |
| 数据库连接失败 | 检查 `application.yml` 地址/账号/密码；先执行 `init.sql` |
| 上传大文件失败 | 检查 nginx `client_max_body_size` 与后端 multipart 限制 |
| 端口占用 | 后端 8090、前端 80/8080 |

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

项目根目录运行一键脚本（自动拉起后端 8090 + 前端 8080）：

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