Merge remote-tracking branch 'origin/main'

xyc

6 小时以前 fbacc121df810f01e5b6ed43e6431dea6df270fd

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

@@ -64,8 +64,9 @@
│  â”œâ”€ sql_city_bus.sql                          åŸŽå¸‚客运-公交月度表（必须执行）
│  â”œâ”€ sql_city_taxi.sql                         åŸŽå¸‚客运-出租月度表/授权表（必须执行）
│  â”œâ”€ sql_wyc.sql                               ç½‘约车全省总量/订单分市州表（必须执行）
│  â”œâ”€ sql_holiday.sql                           ä¸“项统计-重要节假日表（必须执行）
│  â””─ sql_holiday_comparison_base_migration.sql èŠ‚假日旧库升级：普通国省道环比基期字段
│  â”œâ”€ sql_holiday.sql                           ä¸“项统计-重要节假日表（旧库补建时执行）
│  â”œâ”€ sql_holiday_decimal_migration.sql         èŠ‚假日数值列精度迁移（旧库升级）
│  â””─ sql_holiday_comparison_base_migration.sql èŠ‚假日环比基期字段迁移（旧库升级）
└─ README-部署说明.txt
```

@@ -73,9 +74,9 @@

### 5.1 å‡†å¤‡æ•°æ®åº“（两条路线二选一，**不要混着做**）

#### è·¯çº¿ A：全新空库（要跑 5 ä¸ªè„šæœ¬ï¼‰
#### è·¯çº¿ A：全新空库（要跑 4 ä¸ªè„šæœ¬ï¼‰

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

```bash
cd db
@@ -83,12 +84,11 @@
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
mysql --default-character-set=utf8mb4 -u root -p -D traffic_audit < sql_holiday.sql
```

> âš ï¸ **`init.sql` æ˜¯ç ´åæ€§çš„**：里面的基础表都带 `DROP TABLE IF EXISTS`。**已有数据的库上千万不要再跑 init.sql**，否则表数据会被清空重建。
> å·²éƒ¨ç½²è¿‡æ—©æœŸèŠ‚假日模块的现有库，升级前先执行 `sql_holiday_comparison_base_migration.sql` æ·»åŠ  `comparison_base` å­—段；全新库直接使用已更新后的 `sql_holiday.sql`。
> 5 ä¸ªè„šæœ¬å…±è¦†ç›– 33 å¼ è¡¨ï¼ˆinit.sql 28 å¼  + åŸŽå¸‚客运 3 å¼  + ç½‘约车 2 å¼ ï¼‰ã€‚
> æ—©æœŸç‰ˆæœ¬åº“若没有节假日 4 å¼ è¡¨ï¼Œæ‰§è¡Œ `sql_holiday.sql`；若已有节假日表但缺精度或环比基期字段，按需执行两个迁移脚本。
> 4 ä¸ªè„šæœ¬å…±è¦†ç›– 33 å¼ è¡¨ï¼ˆinit.sql 28 å¼ ï¼Œå…¶ä¸­å«èŠ‚假日 4 å¼  + åŸŽå¸‚客运 3 å¼  + ç½‘约车 2 å¼ ï¼‰ã€‚

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

@@ -109,9 +109,9 @@
mysql --default-character-set=utf8mb4 -u root -p < traffic_audit_full_YYYYMMDD.sql
```

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

@@ -223,3 +223,75 @@

- **2026-09-13**：新增一键打包脚本 `package-deploy.py`；jar æ”¹ä¸ºå†…嵌前端（部署机不再需要 nginx）；删除 Redis ç›¸å…³è¯´æ˜Žï¼ˆä»£ç æœªä½¿ç”¨ï¼‰ï¼›è¡¥ `sql_wyc.sql` ä¸Ž `summary.template-dir`；补 `jwt.secret` å–值规则；补部署后验证清单。
- 2026-08-27：首版（zip éƒ¨ç½²åŒ… + nginx æ–¹æ¡ˆï¼‰ã€‚

---

## å¯†é’¥ä¸Žé…ç½®ï¼ˆ2026-09-26 èµ·ï¼Œæ‰“包必读）

### åˆ†å±‚约定

| ä½ç½® | ç”¨é€” | æ˜¯å¦è¿› git | æ˜¯å¦è¿› jar |
| --- | --- | --- | --- |
| `traffic-audit-server/src/main/resources/application.yml` | è¿› jar çš„默认配置，**只有占位符**（`${TRAFFIC_DB_PASSWORD:}`、`${DEEPSEEK_API_KEY:}` ç­‰ï¼‰ | å¦ï¼ˆå·² gitignore，用 `application.yml.example` åšæ¨¡æ¿ï¼‰ | **是**（无真实值） |
| `traffic-audit-server/config/application.yml` | æœ¬æœºå¼€å‘真实值（库口令 / JWT / DeepSeek key） | å¦ï¼ˆå·² gitignore） | å¦ |
| jar åŒçº§çš„ `backend/application.yml` | éƒ¨ç½²æœºçœŸå®žå€¼ï¼ˆä¼˜å…ˆçº§é«˜äºŽ jar å†…置） | å¦ | å¦ï¼ˆåœ¨åŒ…外，现场填） |
| çŽ¯å¢ƒå˜é‡ `TRAFFIC_DB_PASSWORD` / `TRAFFIC_DB_USER` / `TRAFFIC_DB_URL` / `TRAFFIC_JWT_SECRET` / `DEEPSEEK_API_KEY` | è¦†ç›–以上任意一项 | å¦ | å¦ |

### æœ¬æœºå¼€å‘（值放环境变量，不落文件）

```powershell
setx TRAFFIC_DB_PASSWORD "本机 MySQL å£ä»¤"     # è®¾ä¸€æ¬¡å³å¯ï¼Œä¹‹åŽæ–°å¼€çš„终端自动带上
setx DEEPSEEK_API_KEY   "DeepSeek key"
# éœ€è¦æ—¶å†è¦†ç›–：setx TRAFFIC_DB_URL / TRAFFIC_DB_USER / TRAFFIC_JWT_SECRET

powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1   # ä¼šè‡ªåŠ¨ä»Žæ³¨å†Œè¡¨è¡¥é½å¹¶æ³¨å…¥åŽç«¯è¿›ç¨‹
```

- `traffic-audit-server/config/application.yml` åªç•™æ³¨é‡Šè¯´æ˜Žï¼ˆæ— æ˜Žæ–‡ï¼‰ï¼›åˆ æŽ‰å®ƒä¹Ÿä¸å½±å“ï¼ˆå€¼å…¨åœ¨çŽ¯å¢ƒå˜é‡é‡Œï¼‰ã€‚
- è‹¥ç”¨ IDE ç›´æŽ¥è·‘主类，请在**新开的**终端/IDE é‡Œå¯åŠ¨ï¼ˆè®©æ–°ç»ˆç«¯ç»§æ‰¿ç”¨æˆ·çŽ¯å¢ƒå˜é‡ï¼‰ï¼Œæˆ–手动 `setx` åŽé‡å¯ IDE。

### æ‰“包前自查（30 ç§’）

```powershell
# 1) ç¡®è®¤è¿› jar çš„配置没有真实密钥（应只看到 ${...}）
Select-String -Path traffic-audit-server\src\main\resources\application.yml -Pattern "password:|api-key:|secret:"
# 2) æ‰“完包后再验证一次 jar å†…部
python -c "import zipfile;print(zipfile.ZipFile('traffic-audit-server/target/traffic-audit-server-1.0.0-SNAPSHOT.jar').read('BOOT-INF/classes/application.yml').decode('utf-8'))" | Select-String "password:|api-key:"
```


### ä¸€é”®æ‰“包（推荐，2026-09-27 èµ·ï¼‰

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File pack-deploy.ps1
# å¯é€‰å‚数： -OutRoot "E:\试验"   -SkipFrontend
```

脚本做四件事：
1. `mvn clean package -DskipTests` æž„建后端 jar；
2. **解压 jar è‡ªæ£€**：检查 `BOOT-INF/classes/application.yml` æ˜¯å¦å…¨ä¸ºå ä½ç¬¦â€”—一旦发现 `sk-` æˆ–明文口令**直接中止打包**；
3. `npm run build` é‡å»ºå‰ç«¯ `dist`；
4. æŒ‰ `deploy-templates/` ç»„装完整部署包（backend / frontend / db / README-部署说明.txt），输出到 `<OutRoot>\traffic-audit-deploy-<yyyyMMdd>`。

模板件统一放在 **`deploy-templates/`**（已入库）：外部 `application.yml`、`start-backend.cmd/.sh`、`nginx.conf.example`、`db\{init.sql,sql_city_bus,sql_city_taxi,sql_wyc}.sql`、`README-部署说明.txt`。改模板即改打包产物。

### è½®æ¢å¯†é’¥åŽåŒæ­¥æœ¬æœº

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File set-secrets.ps1
```

交互式输入（回车跳过某一项），自动 `setx` åˆ°ç”¨æˆ·çŽ¯å¢ƒå˜é‡å¹¶æç¤ºé‡å¯åŽç«¯ï¼›å€¼ä¸ä¼šå†™å…¥ä»»ä½•æ–‡ä»¶ã€‚

### éƒ¨ç½²æœºä¸ŠåŠ /换 DeepSeek key

1. æ‰“包上传后，编辑 **jar åŒçº§**的 `backend/application.yml`：`deepseek.api-key: "你的新key"`（留空则页面 AI åˆ†æžä¸å¯ç”¨ï¼Œå…¶ä½™åŠŸèƒ½æ­£å¸¸ï¼‰ï¼›
2. é‡å¯åŽç«¯ï¼š`start-backend.cmd`（或 `java -jar traffic-audit-server-1.0.0-SNAPSHOT.jar`）；
3. é¡µé¢é‡Œç‚¹ä¸€æ¬¡ AI åˆ†æžç¡®è®¤å¯ç”¨ï¼›
4. **不要**去改 jar å†…部的配置（改了下次发包就丢），也不要把 key æäº¤è¿›ä»»ä½•ä»“库文件。

### è½®æ¢ï¼ˆä½œåºŸï¼‰å·²æ³„露的 key

1. ç™»å½• DeepSeek æŽ§åˆ¶å° â†’ API Keys â†’ æ–°å»ºä¸€ä¸ª key；
2. åˆ é™¤/禁用旧 key（旧 key ç«‹åˆ»å¤±æ•ˆï¼Œæ­¤å‰æ‰“包带出去的 jar é‡Œé‚£ä»½å³ä½œåºŸï¼‰ï¼›
3. æŒ‰ä¸Šé¢ç¬¬ 1~3 æ­¥æŠŠæ–° key å¡«åˆ°éƒ¨ç½²æœºçš„外部配置并重启验证。