Merge remote-tracking branch 'origin/main'

zhizhijie

9 天以前 eaad844aaabbd14ac2e72d28ecd7e3b5e04e9daf

 docs/´ò°ü²¿Êð˵Ã÷.md

@@ -1,6 +1,6 @@
# äº¤é€šç»Ÿè®¡æŠ¥è¡¨å®¡æ ¸ç³»ç»Ÿ â€” æ‰“包与部署说明

> é€‚用：合并后 main åˆ†æ”¯ï¼ˆ2026-08-27 èµ·ï¼‰ã€‚后端 Spring Boot 2.7（Java 8），前端 Vue 2 + Element UI。
> é€‚用：main åˆ†æ”¯ï¼ˆæœ€æ–°æ›´æ–° 2026-09-13）。后端 Spring Boot 2.7（Java 8），前端 Vue 2 + Element UI。
> æœ¬æ–‡æ¡£é¢å‘开发与部署同事，命令均在 Windows ä¸‹éªŒè¯ã€‚

## ä¸€ã€é¡¹ç›®ç»“æž„
@@ -9,149 +9,213 @@
|------|------|
| `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` | æ•°æ®åº“初始化脚本（建库建表 + åˆå§‹è´¦å·ï¼‰ |
| `docs` | è¿è¡Œæ•°æ®ç›®å½•ï¼ˆæŠ¥è¡¨æ¨¡æ¿ã€æ±‡æ€»å¤§è¡¨æ¯ç‰ˆç­‰ï¼‰ï¼Œ**发布必须带上** |
| `package-deploy.py` | ä¸€é”®æ‰“包脚本（前端构建 â†’ å†…嵌进 jar â†’ ç»„装部署包 â†’ æ‰“ zip） |

## äºŒã€çŽ¯å¢ƒè¦æ±‚

| ç»„件 | ç‰ˆæœ¬ | ç”¨é€” |
| ç»„件 | ç‰ˆæœ¬ | è¯´æ˜Ž |
|------|------|------|
| JDK | 1.8 | åŽç«¯ç¼–译与运行 |
| Maven | 3.x | åŽç«¯æ‰“包 |
| Node.js | 14+ | å‰ç«¯æ‰“包（vue-cli 4.5） |
| MySQL | 8.0 | æ•°æ®åº“（库名 `traffic_audit`） |
| JDK | 1.8 | éƒ¨ç½²æœºå¿…须；后端编译/运行 |
| MySQL | **8.0** | éƒ¨ç½²æœºå¿…须，库名 `traffic_audit`；现网/开发机为 8.0.29，表排序规则是 `utf8mb4_0900_ai_ci`，**目标机装 5.7 ä¼šå¯¼å…¥å¤±è´¥** |
| Maven 3.x / Node.js 14+ | â€” | **只有「在部署机上打包」才需要**；用一键脚本产出的包部署则不需要 |
| Redis | **不需要** | ä»£ç æœªä½¿ç”¨ Redis（旧说明中的 Redis é…ç½®æ˜¯é—留项，可忽略） |
| nginx / IIS | **不需要** | å‰ç«¯å·²å†…嵌进 jar，访问 8090 å³å¯ï¼›è¦å‰åŽç«¯åˆ†ç¦»æ—¶æ‰æ˜¯å¤‡é€‰ |

## ä¸‰ã€æ•°æ®åº“初始化

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

```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
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\target\traffic-audit-server-1.0.0-SNAPSHOT.jar`（可执行 fat jar，约 57MB）。
> æ³¨æ„ï¼šæ‰‹å·¥æ–¹å¼è·‘完记得删掉 `traffic-audit-server/src/main/resources/static` ä¸‹çš„内容，否则会污染源码目录。

### 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\
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
```

关键点：
## äº”、目标机器部署步骤

- **`docs` å¿…须放在 jar åŒçº§**。后端运行时按启动目录向上查找 `docs`（报表导出的 Word æ¨¡æ¿ã€å¯¼å…¥é¡µã€Œä¸‹è½½æ¨¡æ¿ã€ã€ç›®å½•å¯¼å…¥æ•°æ®éƒ½ä»Žè¿™é‡Œè¯»ï¼‰ï¼Œæ‰¾ä¸åˆ°ä¼šæŠ¥ã€Œæœªæ‰¾åˆ°æ•°æ®ç›®å½• docs」或「未找到模板文件 xxx」。
- é¦–次部署直接把项目里的整个 `docs` æ‹·è¿‡åŽ»æœ€ç¨³å¦¥ï¼›åŽç»­å¯ç²¾ç®€ï¼ˆåªç•™æ¨¡æ¿å­ç›®å½•ï¼‰ï¼Œè¯¦è§ã€Œå¸¸è§é—®é¢˜ã€ã€‚
- `application.yml` æ‰“包在 jar å†…；部署机需要改配置时，可在 jar åŒçº§æ”¾ä¸€ä¸ªå¤–ç½® `application.yml`（外置优先级高于内置），或改完再打包。
### 5.1 å‡†å¤‡æ•°æ®åº“（两条路线二选一，**不要混着做**）

## å…­ã€å…³é”®é…ç½®ï¼ˆapplication.yml）
#### è·¯çº¿ A：全新空库（要跑 4 ä¸ªè„šæœ¬ï¼‰

`init.sql` è‡ªå¸¦ `CREATE DATABASE` ä¸Ž `USE traffic_audit`，可独立执行；另外 3 ä¸ªè„šæœ¬æ²¡æœ‰ `USE` è¯­å¥ï¼Œå¿…须用 `-D traffic_audit`（或 `mysql ... traffic_audit < æ–‡ä»¶`）指定库：

```bash
cd db
mysql --default-character-set=utf8mb4 -u root -p            < init.sql          # å»ºåº“ + 24 å¼ åŸºç¡€è¡¨ + é¢„置账号
mysql --default-character-set=utf8mb4 -u root -p -D traffic_audit < sql_city_bus.sql
mysql --default-character-set=utf8mb4 -u root -p -D traffic_audit < sql_city_taxi.sql
mysql --default-character-set=utf8mb4 -u root -p -D traffic_audit < sql_wyc.sql
```

> âš ï¸ **`init.sql` æ˜¯ç ´åæ€§çš„**：里面的基础表都带 `DROP TABLE IF EXISTS`。**已有数据的库上千万不要再跑 init.sql**，否则表数据会被清空重建。
> 4 ä¸ªè„šæœ¬å…±è¦†ç›– 29 å¼ è¡¨ï¼ˆinit.sql 24 å¼  + åŸŽå¸‚客运 3 å¼  + ç½‘约车 2 å¼ ï¼‰ã€‚

#### è·¯çº¿ B：把现网/开发机的数据整套搬过去（推荐，不用跑脚本）

先确认两端 MySQL éƒ½æ˜¯ **8.0**（本库表排序规则为 `utf8mb4_0900_ai_ci`，5.7 ä¸è¯†åˆ«ä¼šå¯¼è‡´å¯¼å…¥å¤±è´¥ï¼‰ï¼Œå¹¶ä¸”**用与服务端同版本的 mysqldump**（不要用 5.7 çš„客户端去导 8.0 æœåŠ¡ç«¯ï¼‰ã€‚

在源机器（本机 MySQL ç«¯å£ç¤ºä¾‹ 3308，按实际改）：

```bash
"C:\Program Files\MySQL\MySQL Server 8.0\bin\mysqldump.exe" ^
  --host=127.0.0.1 --port=3308 --user=root --password=你的密码 ^
  --default-character-set=utf8mb4 --single-transaction --routines --triggers --events ^
  --databases traffic_audit > traffic_audit_full_YYYYMMDD.sql
```

在目标机器：

```bash
mysql --default-character-set=utf8mb4 -u root -p < traffic_audit_full_YYYYMMDD.sql
```

- `--databases` ä¼šæŠŠ `CREATE DATABASE` + `USE` ä¸€èµ·å†™è¿›å¤‡ä»½ï¼Œæ‰€ä»¥ç›®æ ‡æœºå™¨**不用先建库、也不用跑那 4 ä¸ªè„šæœ¬**。
- å¤‡ä»½é‡ŒåŒ…含 `sys_user`，账号密码与源机器完全一致（本机是 `admin / 123456`），不会被重置成 `admin/admin123`。
- âš ï¸ å¤‡ä»½é‡Œæ¯å¼ è¡¨éƒ½å¸¦ `DROP TABLE IF EXISTS`（共 29 å¼ ï¼‰ï¼š**目标库要是已有数据，会被直接覆盖**。请还原到空库，或先自己备份目标库。
- æœ¬æ¬¡å·²ç”Ÿæˆå¹¶**验证过**备份：`traffic_audit_full_20260913.sql`（45.5 MB，8.0.29 å®¢æˆ·ç«¯å¯¼å‡ºï¼‰ã€‚
  éªŒè¯æ–¹å¼ï¼šæŠŠå¤‡ä»½åº“名改成临时库导入，逐表比对 `SHOW CREATE TABLE`（表结构）与 `COUNT(*)`（行数）——**29 å¼ è¡¨ç»“构与行数均 0 å·®å¼‚**，抽查 `wyc_order_monthly` 2026-08 æ•°æ®ä¸€è‡´ï¼ŒéªŒè¯åŽå·²åˆ é™¤ä¸´æ—¶åº“。

#### è·¯çº¿ B2：用 Navicat çš„「备份 / è¿˜åŽŸå¤‡ä»½ã€ï¼ˆ.nb3，最贴近日常习惯）

`.nb3` æ˜¯ Navicat ç§æœ‰å¤‡ä»½æ ¼å¼ï¼ˆtar å®¹å™¨ï¼šæ¯å¼ è¡¨ä¸€ä»½ meta.json + gz åŽ‹ç¼©çš„数据分片 + SHA1 æ ¡éªŒ + æ€» meta.json），
只能由 Navicat è‡ªå·±ç”Ÿæˆã€ä¹Ÿåªèƒ½åœ¨ Navicat é‡Œç”¨ã€Œè¿˜åŽŸå¤‡ä»½ã€è¿˜åŽŸâ€”—**用 `.sql` ç‚¹ã€Œè¿˜åŽŸå¤‡ä»½ã€ä¸€å®šå¤±è´¥**（那个入口只认 .nb3）。

在源机器（30 ç§’）：

1. Navicat â†’ è¿žæŽ¥ `mysql80` â†’ é€‰ä¸­ `traffic_audit` â†’ å³é”® â†’「备份…」→ èµ·ä¸ªåå­— â†’ ç¡®å®šï¼Œç­‰å®ƒè·‘完；
2. ç”Ÿæˆçš„备份文件在 Navicat çš„ profile ç›®å½•ï¼š`D:\文档\Navicat\MySQL\Servers\mysql80\traffic_audit\<时间戳>.nb3`
   ï¼ˆæœ¬æœº 8/27 é‚£ä»½å°±åœ¨è¿™é‡Œï¼Œä½†å®ƒ**已过期**：只有 27 å¼ è¡¨ã€ç¼ºç½‘约车两张表、数据是 8/27 çš„，不要用）。

在目标机器：

3. å…ˆåœ¨ Navicat é‡Œå»ºä¸€ä¸ªè¿žåˆ°æœ¬æœº MySQL 8.0 çš„连接（**连接名建议与源机器一致，比如 `mysql80`**），并新建空库 `traffic_audit`（字符集 utf8mb4）；
4. æŠŠ `.nb3` æ”¾åˆ°ç›®æ ‡æœºå™¨çš„对应目录 `<Navicat profile>\MySQL\Servers\<连接名>\traffic_audit\`（没有就照着建目录）；
5. å³é”®è¯¥åº“ â†’「还原备份」→ åœ¨é€‰æ‹©åˆ—表里勾选这份备份 â†’ å¼€å§‹ï¼ˆåˆ—表里看不到就重启一次 Navicat）。

> ä¸‰ç§æ–¹å¼ï¼ˆè·¯çº¿ A ç©ºåº“ 4 è„šæœ¬ / è·¯çº¿ B å‘½ä»¤è¡Œè¿˜åŽŸ .sql / è·¯çº¿ B2 Navicat .nb3）**任选其一**即可，
> ä½†**不要叠加**：还原完备份后再跑 `init.sql` ä¼šæŠŠæ•°æ®æ¸…空重建。

> æ³¨æ„ï¼š`docs/` ç›®å½•ï¼ˆæŠ¥è¡¨æ¨¡æ¿ã€æ±‡æ€»å¤§è¡¨æ¯ç‰ˆï¼‰**与数据库无关，无论哪条路线都必须一并拷贝**。

### 5.2 æ”¹é…ç½® `backend/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/投资/模板`） |
| `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.example`，真实 `application.yml` ä¸å…¥åº“。
> å¤–ç½® `application.yml` ä¸Ž jar åŒçº§å³ç”Ÿæ•ˆï¼ˆä¼˜å…ˆçº§é«˜äºŽ jar å†…置配置），改完不用重新打包。

## ä¸ƒã€å¯åŠ¨åŽç«¯
### 5.3 å¯åŠ¨ï¼ˆå¿…须在 `backend` ç›®å½•ä¸‹ï¼‰

```powershell
cd deploy
java -jar app.jar
# Windows：双击 start-backend.cmd；或
cd backend ; java -jar traffic-audit-server-1.0.0-SNAPSHOT.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 å¯¹é½
}
```bash
# Linux
cd backend && sh start-backend.sh
```

## ä¹ã€éƒ¨ç½²åŽéªŒè¯
成功标志：日志出现 `Started TrafficAuditApplication` ä¸Ž `Tomcat started on port(s): 8090`。

1. æµè§ˆå™¨æ‰“å¼€ `http://<服务器>/`；
2. ç”¨ `admin / admin123` ç™»å½•ï¼ˆç”Ÿäº§æ”¹å¯†åŽä½¿ç”¨æ–°å¯†ç ï¼‰ï¼›
3. æ•°æ®å¯¼å…¥ï¼šä¸‹è½½æ¨¡æ¿ â†’ ä¸Šä¼  Excel（或目录导入）；
4. æŠ¥è¡¨ï¼šæŸ¥è¯¢ â†’ é¢„览/导出（依赖 `docs` æ¨¡æ¿æ–‡ä»¶ï¼‰ï¼›
5. AI åˆ†æžï¼šéœ€é…ç½® `deepseek.api-key` åŽå¯ç”¨ã€‚
### 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」 | å½“前运行目录不对；把 `docs` æ”¾åˆ° jar åŒçº§å†å¯åŠ¨ |
| å¯¼å‡ºæŠ¥ã€Œæœªæ‰¾åˆ°æ¨¡æ¿æ–‡ä»¶ xxx」 | `docs` å¯¹åº”子目录缺模板文件；首次部署拷整个 `docs` |
| é¡µé¢èƒ½å¼€ä½†æŽ¥å£ 502/404 | nginx æ²¡é… `/api` åä»£ï¼Œæˆ–后端没启动成功 |
| æ•°æ®åº“连接失败 | æ£€æŸ¥ `application.yml` åœ°å€/账号/密码；先执行 `init.sql` |
| ä¸Šä¼ å¤§æ–‡ä»¶å¤±è´¥ | æ£€æŸ¥ nginx `client_max_body_size` ä¸ŽåŽç«¯ multipart é™åˆ¶ |
| ç«¯å£å ç”¨ | åŽç«¯ 8090、前端 80/8080 |
| å¯åŠ¨æŠ¥ã€Œæœªæ‰¾åˆ°æ•°æ®ç›®å½• 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 |

## åä¸€ã€å¼€å‘环境日常启动

项目根目录运行一键脚本（自动拉起后端 8090 + å‰ç«¯ 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 æ–¹æ¡ˆï¼‰ã€‚