docs(version): record pushed v1.0.0 tag

xyc

2 天以前 540f610eaa5ecdda1e876162d3dbee809ce678e1

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

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

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

## ä¸€ã€é¡¹ç›®ç»“æž„
@@ -34,8 +34,8 @@

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）。
3. ç»„装 `deploy/traffic-audit-deploy-YYYYMMDD-v1.0.0/`；
4. åŽ‹ç¼©ä¸º `traffic-audit-deploy-YYYYMMDD-v1.0.0.zip`（约 70 MB）。

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

@@ -47,18 +47,48 @@

> æ³¨æ„ï¼šæ‰‹å·¥æ–¹å¼è·‘完记得删掉 `traffic-audit-server/src/main/resources/static` ä¸‹çš„内容，否则会污染源码目录。

### ç‰ˆæœ¬ç®¡ç†ä¸Žå‘布（2026-10-05 èµ·ï¼‰

采用方案 A：后端 jar ä½¿ç”¨å›ºå®šæ–‡ä»¶åï¼Œç‰ˆæœ¬å·ç”± `pom.xml` å•ä¸€æ¥æºç”Ÿæˆï¼Œå‘布包名和 git tag å¸¦ç‰ˆæœ¬ã€‚

- å•ä¸€ç‰ˆæœ¬æºï¼š`traffic-audit-server/pom.xml` çš„ `<version>`，例如 `1.0.0`
- æž„建产物固定为 `traffic-audit-server/target/traffic-audit-server.jar`
- æž„建时自动把版本写进：
  - `BOOT-INF/classes/app-version.properties`
  - `META-INF/MANIFEST.MF` çš„ `Implementation-Version`
- å‘布包命名：`traffic-audit-deploy-YYYYMMDD-v1.0.0(.zip)`
- git tag å‘½åï¼š`v1.0.0`
- é¡µé¢ç‰ˆæœ¬ï¼šåŽç«¯ `GET /api/version`，登录页和页头显示 `V1.0.0`
- `pack-deploy.ps1` ä¼šæ ¡éªŒ `pom.xml`、jar å†… `app-version.properties`、jar æ¸…单三者版本一致，不一致直接中止打包

发新版本流程：

1. å…ˆæ”¹ `traffic-audit-server/pom.xml` çš„ `<version>`，例如 `1.0.1`
2. è¿è¡Œ `pack-deploy.ps1` æ‰“包
3. æäº¤ä»£ç å¹¶æ‰“ git tag：`git tag -a v1.0.1 -m "v1.0.1"`
4. æœåŠ¡å™¨åœæ­¢æœåŠ¡ï¼Œæ›¿æ¢ `traffic-audit-server.jar`，再启动服务

旧服务器首次升级（只需做一次）：已有 `trafficAudit.xml` é€šå¸¸ä»å†™æ­»æ—§ jar å `traffic-audit-server-1.0.0-SNAPSHOT.jar`，把 `<arguments>` æ”¹æˆå›ºå®šæ–‡ä»¶åï¼š

```xml
<arguments>-Dfile.encoding=UTF-8 -jar "%BASE%\traffic-audit-server.jar"</arguments>
```

以后每次发布只替换 jar å¹¶é‡å¯æœåŠ¡ï¼Œä¸å†ä¿®æ”¹ `trafficAudit.xml`。

## å››ã€éƒ¨ç½²åŒ…内容

```
traffic-audit-deploy-YYYYMMDD/
traffic-audit-deploy-YYYYMMDD-v1.0.0/
├─ backend/
│  â”œâ”€ traffic-audit-server-1.0.0-SNAPSHOT.jar   åŽç«¯ + å†…嵌前端（约 55 MB）
│  â”œâ”€ traffic-audit-server.jar                   åŽç«¯ + å†…嵌前端（约 55 MB，固定文件名）
│  â”œâ”€ docs/                                     æ¨¡æ¿ä¸Žè¿è¡Œæ•°æ®ï¼ˆå¿…需，勿删）
│  â”œâ”€ application.yml                           å¤–部配置（改这里即可，无需重打包）
│  â”œâ”€ start-backend.cmd / start-backend.sh      å¯åŠ¨è„šæœ¬ï¼ˆäººå·¥åŒå‡»/命令行）
│  â”œâ”€ trafficAudit.exe                          WinSW æœåŠ¡åŒ…装器（2.12.0 x64，自包含 .NET 6）
│  â”œâ”€ trafficAudit.xml                          WinSW æœåŠ¡é…ç½®ï¼ˆè‡ªåŠ¨/延迟启动、失败重启、日志滚动）
│  â”œâ”€ install-service.ps1                       æ³¨å†Œ/查看/重启/删除 Windows æœåŠ¡ï¼ˆå¼€æœºè‡ªå¯ï¼ŒæŽ¨èï¼‰
│  â”œâ”€ install-service.cmd                       åŒå‡»å…¥å£ï¼šæ³¨å†Œå¼€æœºè‡ªå¯æœåŠ¡ï¼ˆè‡ªåŠ¨è¯·æ±‚管理员权限）
│  â”œâ”€ install-service.ps1                       ä¸Šé¢é‚£ä¸ª cmd å®žé™…调用的脚本（注册/查看/重启/删除）
│  â”œâ”€ start-backend-service.cmd                 å¤‡é€‰ï¼šéžäº¤äº’启动器（无 pause、写 app.log）
│  â”œâ”€ install-autostart.ps1                     å¤‡é€‰ï¼šæ³¨å†Œ/查看/删除 Windows å¼€æœºè‡ªå¯è®¡åˆ’任务
│  â””─ web/                                     å‰ç«¯é™æ€æ–‡ä»¶ï¼ˆç”± dist è‡ªåŠ¨åŒæ­¥ï¼Œ8090 å•ç«¯å£æ¨¡å¼å¿…需）
@@ -72,7 +102,8 @@
│  â”œâ”€ sql_wyc.sql                               ç½‘约车全省总量/订单分市州表（必须执行）
│  â”œâ”€ sql_holiday.sql                           ä¸“项统计-重要节假日表（旧库补建时执行）
│  â”œâ”€ sql_holiday_decimal_migration.sql         èŠ‚假日数值列精度迁移（旧库升级）
│  â””─ sql_holiday_comparison_base_migration.sql èŠ‚假日环比基期字段迁移（旧库升级）
│  â”œâ”€ sql_holiday_comparison_base_migration.sql èŠ‚假日环比基期字段迁移（旧库升级）
│  â””─ sql_holiday_previous_day_migration.sql    èŠ‚假日前一日配置迁移（旧库升级）
└─ README-部署说明.txt
```

@@ -93,7 +124,7 @@
```

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

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

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

```bash
@@ -171,11 +202,13 @@

### 5.4 Windows å¼€æœºè‡ªå¯ï¼ˆæŽ¨èï¼šæ³¨å†Œæˆ Windows æœåŠ¡ï¼‰

在 `backend` ç›®å½•ä¸‹ç”¨**管理员** PowerShell æ‰§è¡Œï¼ˆ`trafficAudit.exe` / `trafficAudit.xml` / `install-service.ps1` å·²éšåŒ…提供）：
在 `backend` ç›®å½•é‡Œ**右键 `install-service.cmd` â†’「以管理员身份运行」**即可（直接双击也行，它会自己弹 UAC）。它实际调用的就是同目录的 `install-service.ps1`，等价命令：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File install-service.ps1
```

脚本会自动定位 java、注册服务、启动，然后探测端口打印结果；起不来时直接打印 `logs\*.log` çš„最后 15 è¡Œã€‚

| é¡¹ | å€¼ |
|----|----|
@@ -266,6 +299,7 @@

## åä¸€ã€å˜æ›´è®°å½•

- **2026-10-05**：版本管理采用方案 A。`pom.xml` ä¸ºå”¯ä¸€ç‰ˆæœ¬æºï¼Œjar å›ºå®šåä¸º `traffic-audit-server.jar`，构建自动注入 `app-version.properties` ä¸Ž `MANIFEST.MF`；发布包名带版本，新增 `/api/version` é¡µé¢æ˜¾ç¤ºï¼Œé¦–次升级旧服务器需一次性修改 `trafficAudit.xml`，以后只替换 jar å¹¶é‡å¯ã€‚
- **2026-10-03**：`pack-deploy.ps1` è¡¥é½å¤–ç½® `application.yml`/`docs`/`db`/启动脚本并同步 `backend\web`（修 `Access denied ... (using password: NO)`）；模板端口 8080→8090；新增 Windows æœåŠ¡æ–¹å¼å¼€æœºè‡ªå¯ï¼ˆWinSW 2.12.0 `trafficAudit.exe` + `trafficAudit.xml` + `install-service.ps1`，自动/延迟启动、失败重启、日志滚动），计划任务方式降为备选；补操作系统兼容性说明。
- **2026-09-13**：新增一键打包脚本 `package-deploy.py`；jar æ”¹ä¸ºå†…嵌前端（部署机不再需要 nginx）；删除 Redis ç›¸å…³è¯´æ˜Žï¼ˆä»£ç æœªä½¿ç”¨ï¼‰ï¼›è¡¥ `sql_wyc.sql` ä¸Ž `summary.template-dir`；补 `jwt.secret` å–值规则；补部署后验证清单。
- 2026-08-27：首版（zip éƒ¨ç½²åŒ… + nginx æ–¹æ¡ˆï¼‰ã€‚
@@ -302,7 +336,7 @@
# 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:"
python -c "import zipfile;print(zipfile.ZipFile('traffic-audit-server/target/traffic-audit-server.jar').read('BOOT-INF/classes/application.yml').decode('utf-8'))" | Select-String "password:|api-key:"
```


@@ -317,7 +351,7 @@
1. ç”¨ `deploy-templates/jar-application.yml`（全占位符）临时替换源码 `application.yml`，再 `mvn clean package -DskipTests`，构建后自动还原开发机真实配置；
2. **解压 jar è‡ªæ£€**：检查 `BOOT-INF/classes/application.yml` æ˜¯å¦å…¨ä¸ºå ä½ç¬¦â€”—一旦发现 `sk-` æˆ–明文口令**直接中止打包**；
3. `npm run build` é‡å»ºå‰ç«¯ `dist`；
4. æŒ‰ `deploy-templates/` ç»„装完整部署包（backend / frontend / db / README-部署说明.txt）——`backend/` å« jar、`application.yml`、启动脚本、`docs/`、`web/`（由 dist è‡ªåŠ¨åŒæ­¥ï¼Œä¾› 8090 å•ç«¯å£æ¨¡å¼ï¼‰ï¼Œä»¥åŠ Windows æœåŠ¡ä¸‰ä»¶å¥— `trafficAudit.exe` + `trafficAudit.xml` + `install-service.ps1`，输出到 `<OutRoot>\traffic-audit-deploy-<yyyyMMdd>`；
4. æŒ‰ `deploy-templates/` ç»„装完整部署包（backend / frontend / db / README-部署说明.txt）——`backend/` å« jar、`application.yml`、启动脚本、`docs/`、`web/`（由 dist è‡ªåŠ¨åŒæ­¥ï¼Œä¾› 8090 å•ç«¯å£æ¨¡å¼ï¼‰ï¼Œä»¥åŠ Windows æœåŠ¡ä¸‰ä»¶å¥— `trafficAudit.exe` + `trafficAudit.xml` + `install-service.ps1`，输出到 `<OutRoot>\traffic-audit-deploy-<yyyyMMdd>-v<version>`；
   WinSW ä¼˜å…ˆç”¨ `deploy-templates\tools\winsw.exe` ç¼“存（校验 SHA-256），缓存缺失或哈希不符时自动从 GitHub å®˜æ–¹å‘布页下载 v2.12.0 x64（该产物未做 Authenticode ç­¾åï¼Œå› æ­¤ä»¥å›ºå®š SHA-256 ä½œå®Œæ•´æ€§æ ¡éªŒï¼‰ï¼›
5. å¯¹ç»„装后的整包再扫一遍明文密钥。

@@ -340,7 +374,7 @@
### éƒ¨ç½²æœºä¸ŠåŠ /换 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`）；
2. é‡å¯åŽç«¯ï¼š`start-backend.cmd`（或 `java -jar traffic-audit-server.jar`）；
3. é¡µé¢é‡Œç‚¹ä¸€æ¬¡ AI åˆ†æžç¡®è®¤å¯ç”¨ï¼›
4. **不要**去改 jar å†…部的配置（改了下次发包就丢），也不要把 key æäº¤è¿›ä»»ä½•ä»“库文件。