docs: add 2026-10-05 shutdown snapshot

xyc

2 天以前 0d3f36094d5fbeb91026fd3a1649ce0759ea6212

 HANDOFF.md

@@ -4,7 +4,34 @@
> **每天结束时**：把当天进展、踩过的坑、新需求、未完成事项更新到本文件，然后可以放心开新对话。
> **协作约定（2026-08-31）**：说「提交」= 本地 commit + 推送到远端 git（origin main，Gitblit），不再只做本地 commit。

## 最新（2026-10-04）
## 最新（2026-10-05）

### 10-05 上午：关机快照（当前状态）

- **已完成**：v1.0.0 正式发布包 `deploy/traffic-audit-deploy-20261005-v1.0.0/`（zip **77.78 MB**）已生成，去密自检、版本自检、结构核对与真实启动冒烟均通过，待上传服务器。版本管理代码与文档均已提交推送（`main` = `93b36c8`）。
- **运行状态**：关机前本机 dev 服务仍在运行（后端 8090 java PID 64112、前端 8080 node PID 46472），随关机停止，无需处理；打包冒烟用的 8095 实例已停止、端口已释放。
- **工作区**：除若干本地临时文件（`_tmp_*`）与一份专项统计 xls 外，git 工作区与远端 `main` 一致；`docs/工作日结/`、`docs/功能测试报告/` 等按约定不入库。
- **下次接手**：先读根目录 `AGENTS.md` + 本文件；待办见第九节（数值精度统一改造、态势感知图、AI 助手 RAG、经济指标试算等），首要事项是跟进正式包在服务器的部署结果。

### 10-05 上午：正式发布包按新版本管理重新生成（v1.0.0，单端口瘦包）

- **背景**：`8b71049` 已把打包脚本改为固定 jar 名 + 版本自检（`traffic-audit-server.jar`、包名带 `v{version}`），但正式发布包还没按新脚本重新生成；版本改造前产出的 `deploy/traffic-audit-deploy-20261005-2/` 仍是旧 jar 名 `traffic-audit-server-1.0.0-SNAPSHOT.jar`。
- **重新生成**：`powershell -NoProfile -ExecutionPolicy Bypass -File pack-deploy.ps1 -NoFrontendDist -SkipServiceWrapper`（后端 clean package 重建、前端 `npm run build` 重建）。
- **产物**：`deploy/traffic-audit-deploy-20261005-v1.0.0/`（351 文件 / 94.58 MB），zip **77.78 MB**。
- **校验**：去密自检 + 版本自检通过（pom / `app-version.properties` / `MANIFEST.MF` 三者均 `1.0.0`）；包内 `backend\traffic-audit-server.jar` 为固定名；无 `frontend/`、无 `trafficAudit.exe/.xml/install-service*`；`backend\web` 44 文件与 `frontend\dist` 逐文件 SHA-256 一致；`README-部署说明.txt` 头部为「20261005，版本 v1.0.0」并含旧服务器一次性升级说明。
- **启动冒烟（真实包、只读）**：用本地开发库配置在 8095 端口启动包内 jar，`GET /api/version` 返回 `{"version":"1.0.0",...}`，`GET /` 返回登录页 200；验证后已按 PID 58652 精确停止冒烟进程。
- **状态**：待用户上传服务器。`deploy/traffic-audit-deploy-20261005-2/`（及更早的 `20261005/`）作废勿用。旧服务器首次升级按 README：先改 `trafficAudit.xml` 的 `<arguments>` 为 `-Dfile.encoding=UTF-8 -jar "%BASE%\traffic-audit-server.jar"` 再换 jar，以后只替换 jar。

### 10-05：版本管理采用方案 A（固定 jar 名，用户验收通过）

- **用户决策**：采用方案 A。`traffic-audit-server/pom.xml` 为唯一版本源，当前对外版本 `1.0.0`。
- **构建改造**：`<finalName>traffic-audit-server</finalName>`，产物固定为 `target/traffic-audit-server.jar`；Maven 资源过滤生成 `app-version.properties`（Spring Boot 父 POM 使用 `@project.version@` 分隔符），`maven-jar-plugin` 写入 `Implementation-Version`。
- **页面显示**：新增免登录 `GET /api/version`；登录页和页头显示 `V1.0.0`。同时修复可执行 jar 下 `buildTime` 为 `null` 的嵌套 URI 解析问题。
- **发布链路**：服务 XML、启动脚本、打包脚本全部改用固定 jar 名；`pack-deploy.ps1` 会校验 pom / `app-version.properties` / `MANIFEST.MF` 三者版本一致，发布包名为 `traffic-audit-deploy-YYYYMMDD-v1.0.0(.zip)`，并输出带 `{version}` 的部署 README。
- **旧服务器首次升级（仅一次）**：停止服务后，把 `trafficAudit.xml` 的 `<arguments>` 改为 `-Dfile.encoding=UTF-8 -jar "%BASE%\traffic-audit-server.jar"`，替换 jar 后启动。以后发版只替换 jar 并重启，不再改 XML。
- **验证**：`mvn -o test`、`mvn -o clean package -DskipTests`、固定名 jar 实际启动并访问 `/api/version`、前端 `npm run build`、本地浏览器登录页显示 `V1.0.0`、`pack-deploy.ps1 -SkipFrontend -NoFrontendDist -SkipServiceWrapper` 组装/去密/版本自检全部通过；负向验证确认版本不匹配和 `SNAPSHOT` 都会在打包前中止。测试报告：本地 `docs/功能测试报告/功能测试报告_版本管理方案A_2026-10-05.md`（目录不入库）。
- **状态**：版本管理代码提交为 `8b71049`，`main` 已同步；`v1.0.0` 已推送到公司 Gitblit并指向 `21a5bf7`。2026-10-05 用户确认本地登录页及所有登录后页面均正确显示 `V1.0.0`。正式发布包已于 10-05 上午用新版打包脚本重新生成（见上方 10-05 上午一节）。

### 10-04 深夜：折线数值标签回到贴近本点（v35，待用户验收）

- **用户反馈**：v31「避开折线」版本不如上一版 v27 —— 虽然标签不压线了，但很多标签离自己的数据点太远，一眼看不出标的是哪个点。要求回到贴近本点的效果。
@@ -17,14 +44,15 @@
- **其余验证**：`mvn compile`/`mvn test` 通过（无编译告警遗留）；Word COM 8 页 15 图（1+2×7）；RapidOCR 复检 12 张折线图数值标签包围框重叠数 = 0；`label_affinity` 复检图 11 每个数据标签到本线 3~8px 且本线是最近线（无「CLOSER TO 其他色」）；放大 6× 复核图 11 左上标签确为 `630.99`（低分辨率 OCR 曾误读为 `1630.99`）。v27↔v35 像素差约 1%，集中在标签处，即白描边生效且未破坏折线。
- **产物与状态**：`_tmp_holiday_verify/holiday_trend_2026-10-04_v35.docx`；下载副本 `C:\Users\jcxiong\Downloads\2026年十一假期全省综合运输客流量走势图（修改版-数字贴近折线-白边清晰）.docx`。未导入、覆盖或重导任何数据。待用户验收；验收前不提交、不推送；现有 `deploy/traffic-audit-deploy-20261004.zip` 仍是 v24 行为，验收后需重建。

### 10-05：走势图 v35 验收通过 + 单端口瘦包发布（ -NoFrontend ）
### 10-05：走势图 v35 验收通过 + 单端口发布包（-NoFrontendDist -SkipServiceWrapper）

- **验收**：v35（折线数值标签回到贴近本点 + 白描边）2026-10-05 用户验收通过。
- **打包需求**：服务器单端口部署，前端本次未变动，要求发布包不含前端以缩小体积。
- **打包工具**：`pack-deploy.ps1` 新增 `-NoFrontend`。开启后不执行 npm 构建、不要求 `traffic-audit-web\dist`、不生成 `frontend\`、不复制 `backend\web`；其余（占位符构建 + 去密自检 + db + docs + README + WinSW）照旧。部署机保留上一版 `backend\web`，本次只替换 jar。
- **发布包**：`deploy/traffic-audit-deploy-20261005/`（311 文件 / 105.71 MB；zip 83.60 MB）。已核对：无 `frontend/`、无 `backend\web`；jar 内置配置全占位符（去密自检通过）；包内 `HolidayTrendChartService.class` 与 `target/classes` 一致（即含 v35 代码）。体积说明：前端 dist 仅约 4.8 MB，包体主要来自 jar（56.3 MB）与 WinSW（17.4 MB）。
- **部署注意**：本包不含前端，部署时不要删除部署机原有 `backend\web\`，否则页面 404；只覆盖 jar（及按需 application.yml）。
- **状态**：已打包，待用户上传到服务器。
- **打包需求（用户澄清）**：服务器单端口，只需要 `backend\web`，不要独立的 `frontend/dist`；为保证包完整，`backend\web` + jar + docs 都要。服务器非首次发布、服务已装，可加 `-SkipServiceWrapper` 去掉服务注册器。
- **打包工具修正**：先前加的 `-NoFrontend` 语义错了（把 `backend\web` 也去掉了），现改为 `-NoFrontendDist`。它只跳过独立 `frontend\` 目录（不复制 dist / nginx 示例），**仍构建（或要求）dist 并同步 `backend\web`**（单端口必需，否则页面 404）。`-SkipFrontend` 仍为“不重建、复用现有 dist”。
- **发布包**：`deploy/traffic-audit-deploy-20261005-2/`（351 文件 / 94.55 MB；zip **77.78 MB**）。已核对：无 `frontend/`、无 `trafficAudit.exe/.xml/install-service*`（服务包装器已排除）；`backend\web` 44 文件与 `frontend\dist` 逐文件哈希一致；jar 内置配置全占位符（去密自检通过）；包内 `HolidayTrendChartService.class` 与 `target/classes` 一致（含 v35 代码）。较上一完整包（110.49 MB / zip 83.77 MB）省约 16 MB 解压 / 6 MB 压缩。
- **作废**：`deploy/traffic-audit-deploy-20261005/`（错误语义下的产物，缺 `backend\web`）已被 `-2` 取代，勿用。
- **部署注意**：覆盖 jar（及按需 `application.yml`）即可；`backend\web` 已随包提供。服务已装，无需重新注册。
- **状态**：已打包，待用户上传到服务器；该包为版本改造前产物，已由 10-05 上午的 `traffic-audit-deploy-20261005-v1.0.0` 取代（勿用）。

### 10-04 深夜：折线数值标签避开折线并贴近本线（v31，待用户验收）