fix(holiday): 拥挤度标签恢复两位小数

xyc

昨天 2f3c2d2851f7693357feb9e62a56a64670755c6a

 HANDOFF.md

@@ -6,7 +6,51 @@

## 最新（2026-10-06）

### 10-06：普通国省道「环比基期」改为人工备用值（不再参与计算）
### 10-06：平均拥挤度标签恢复为 2 位小数

- **调整**：按用户要求，“普通国省道观测站平均拥挤度”不再单独使用 3 位小数，恢复为折线图默认 2 位。
- **一致性**：由于折线图现已统一按显示标签精度绘制，10-04、10-05 的拥挤度都会显示并绘制为 `0.49`，不会再出现同标签不同高度。
- **验证**：后端全量 `mvn -q test -f traffic-audit-server\pom.xml` 通过。

### 10-06：折线图统一按显示标签精度绘制

- **口径（用户 2026-10-06 确认）**：同一张折线图中，同一个显示标签必须对应同一个点位高度；分析文字不得引用比该图显示精度更细的差异。
- **实现**：`HolidayTrendChartService.lineChart` 在所有原始统计计算完成后，于最终入图边界调用 `displayValue`；普通图按该图 `valueDecimals` 做 `HALF_UP` 舍入，百分比点标签按 1 位百分比精度（即原始小数 3 位）舍入。折线坐标和点标签共用同一舍入值，纵轴格式沿用该图精度。
- **边界**：只在最终图表显示层舍入，不改数据库、不改累计、快报、同比、环比或调整口径；该规则用于静态分析报告图，不能让文字引用图上无法分辨的微小差异。
- **验证**：`HolidayTrendChartServiceTest` 聚焦测试通过；后端全量 `mvn -q test -f traffic-audit-server\pom.xml` 通过。新增测试覆盖“两个不同原值按 2 位标签舍入后生成相同几何”和百分比精度换算。测试报告：`docs/功能测试报告/功能测试报告_折线图按标签精度绘制_2026-10-06.md`（本地留存，不入库）。

### 10-06：观测站平均拥挤度走势图改为 3 位小数

- **问题**：用户导入 10-05 观测站数据后反馈，最后一张拥挤度图中 10-04、10-05 标签都显示 `0.49`，但点位高度不同。
- **根因**：平均拥挤度原值分别为 `0.490890014472` 和 `0.492414492754`，折线按未取整原值绘制，标签原为最多 2 位小数，导致标签精度与图形精度不一致，不是日汇总或点位计算错误。
- **修正**：`HolidayTrendChartService.lineChart` 新增可选 `valueDecimals`，默认仍为 2；仅“普通国省道观测站平均拥挤度”图传 3 位。10-04、10-05 现在分别显示 `0.491`、`0.492`，其余图口径不变。
- **验证**：后端全量 `mvn -q test -f traffic-audit-server\pom.xml` 通过；重启后只读生成新 DOCX，OCR 标签为 `0.504/0.476/0.467/0.491/0.492`；与用户提供的文档逐图比对，15 张图中仅拥挤度图 `image15` 变化，其他 14 张 SHA-256 完全一致。测试报告：`docs/功能测试报告/功能测试报告_拥挤度走势图精度_2026-10-06.md`（本地留存，不入库）。
- **数据边界**：未导入、覆盖或重导任何业务数据。

### 10-06：往年国省道调整列表补充调整前值

- **改动**：调整列表接口在同一年份、同一日期、普通国省道口径下，从 `holiday_vehicle_flow` 补返回 `originalValue`；没有原始记录时保持空，页面不显示占位符。表格新增“调整前国省道车流量（万辆次）”，原“调整后国省道车流”改为“调整后国省道车流量”。
- **弹窗**：新增/编辑弹窗同步增加只读“调整前国省道车流量（万辆次）”；编辑已有记录时展示 `originalValue`，无原值或新选择日期时不显示内容。切换年份或日期会清空旧原值，避免错日展示。
- **随日期刷新**：新增接口 `GET /api/holiday/adjustments/source-value`，按所选年份和日期实时读取普通国省道原值；新增/编辑弹窗选日期后自动刷新，未查到源数据时显示为空。前端用请求序号丢弃迟到的旧请求，避免快速换日期时串值。
- **边界**：`originalValue` 只是列表展示字段，标记为 `@TableField(exist = false)`，不写库、不参与调整、环比分母、累计或走势图计算。
- **验证**：`mvn -o test` 11 个测试全部通过；`npm run build` 通过；本地重启后只读核对 2025-10-03/04/05 原值分别为 `362.0035/337.9501/334.2040`，无源数据的 2025-10-09 返回空。测试报告：`docs/功能测试报告/功能测试报告_往年国省道调整原值展示_2026-10-06.md`（本地留存，不入库）。

### 10-06：方案 D 已实现（往年国省道调整表 + 环比基期只作用于前一日分母）

- **最终口径**：`HolidayStatService.loadVehicleByDate` 先用 `holiday_vehicle_adjustment` 覆盖对应历史年份的“当日值”，供走势图、同比、累计和快报使用；随后构造“前一日环比分母”，若前一日普通国省道 C 列有值，则用 C 替换该日前一日国省道值，并据此重算非营业性人员流动量、公路人员流动量和总计。所有环比行只继承这份分母。
- **关键边界**：C 只影响“下一日的环比分母”，不影响 C 所在日的当日值、累计或走势图；调整表只维护历史年份（`year < 当前年份`），2026 年调整仍由导入 Excel 的 D 列进入当日值。
- **本轮实现**：新增 `holiday_vehicle_adjustment` 表及 mapper/service/controller；前端在专项统计-节假日页的“节假日数据”和“观测站分日调查数据”之间新增“往年国省道数据调整”卡片（后续按用户提议保持该位置），支持年份筛选、新增、编辑、删除和原因留痕；部署脚本与 migration 清单已同步。
- **10-04 导入预检（只读，不写库）**：用 `C:\Users\jcxiong\Downloads\2026年十一数据 (2).xlsx` 以 `allowHistoricalOverwrite=false` 调导入接口，返回确认项：
  - `第4日 2026-10-04 普通国省道：原值 323.6551，导入值 322.7695`
  - `第3日 2026-10-03 普通国省道环比基期：原值 空，导入值 320.2418`
  因此 C5 由空变有值不会硬拒绝导入，只会要求历史变更确认；用户确认后即可随调整后的 Excel 重导写入。
- **当前库状态**：本地 `traffic_audit.holiday_vehicle_adjustment` 已执行 DDL（0 行）；2026-10-04 业务值仍为旧值 `323.6551`，等待用户自行重导调整后的 Excel。助手未执行任何业务数据导入、覆盖或重导。
- **验证**：后端 `mvn -o test` 9 个测试全绿（含 C5 只改 10-04 环比分母、历史调整进入 2025 当日值）、前端 `npm run build` 通过；页面实测“往年国省道数据调整”卡片与新增弹窗正常。
- **取整口径（用户 2026-10-06 确认）**：不做“从原始值一次取整”的备选。唯一要求是与 Excel 显示值一致：先按源 Excel 单元格格式生成显示值，再按快报统一 1 位小数。10-04 总计环比原始值约 `4.5481%`，源格显示 `4.55%`，快报取 1 位得到 `4.6%`；这属于既定口径，不是需要修正的边界问题。

> 说明：本文件早前“环比基期只作备用、不参与计算”的段落已作废。该版本针对的是旧实现误把 C 放到 C 所在日本身计算的问题；自方案 D 起，C 的正确语义是**前一日环比分母的调整值**。

### 10-06（已作废，见上方方案 D）：普通国省道「环比基期」改为人工备用值（不再参与计算）

- **背景**：10-04 鄂州樊家庄站中小客流量断崖下跌（35419 -> 8856），领导要求剔除。手工稿快报的做法是：先用剔站后的数值算出 10-04 环比，把 10-03 国省道值挪到「环比基期」C 列备用，再把 10-03 恢复原值以免影响累计。用户明确口径：**「环比基期」只用于数据备用，不参与任何计算**。
- **旧行为（错）**：`HolidayStatService.nationalProvincialRingRatio` 在 2026 年只要 `comparison_base` 有值就按「当日 / 环比基期 - 1」算国省道环比；导出时 E 列写 `=(D{行}-C{行})/C{行}`。按手工稿的 C 列摆法（基期放在被比日那行），这样算还会错位（10-03 环比被算成 +1.11%）。
@@ -306,7 +350,7 @@
- **Excel 浮点精度（2026-10-02 追加）**：参考 `docs/Excel浮点数存储.txt`，新增 `HolidayNumberUtils`（`NumberToTextConverter.toText` + `BigDecimal`，`MathContext(15, HALF_UP)`）；节假日模块由 `Double` 全面改 `BigDecimal`；三张表数值列改 `DECIMAL(30,15)`；库内 6 条客运系数由 2.3999999999999995 校正为 2.4。迁移脚本 `docs/sql_holiday_decimal_migration.sql`。
- **菜单顺序**：“专项统计”已移到“报表生成”之后，当前为 报表生成 -> 专项统计 -> 规则管理 -> 用户管理 -> 系统配置。
- **节假日删除复活修复（2026-10-02 追加）**：原初始化逻辑每次启动补齐缺失的第 N 日，导致 admin 删除 2026-10-08 后被重新插入；现改为仅 `holiday_calendar` 整表为空时首次初始化。重启后 2026 年十一保持 10-01 至 10-07 共 7 天。
- **普通国省道环比基期（2026-10-02 追加）**：普通国省道 C 列为可选环比基期，仅 2026 年启用；填写后只影响普通国省道车流量自身环比 `当日 / 基期 - 1`，未填写按前一日。`holiday_vehicle_flow.comparison_base` 已入库，导入导出与历史变更确认均已接入；折算人员流动量、总人员流动量和 Word 快报继续按 Excel 原公式，不受基期影响。2024/2025 不使用。
- **普通国省道环比基期（2026-10-02 追加，2026-10-06 方案 D 已修正）**：C 列语义最终确定为“下一日环比分母的调整值”；填写后只影响下一日的环比分母，不影响 C 所在日及累计、走势图。`holiday_vehicle_flow.comparison_base` 已入库，导入导出与历史变更确认均已接入。
- **快报首日口径（2026-10-02 追加）**：假期第1天没有前一日环比基数，正文不输出“环比增长/下降/持平”短语，表格当日环比列为“—”；第2天起仍按实际前一日输出环比。已用 2025-10-01/02 快报回归验证。
- **快报百分比精度（2026-10-02 追加）**：Word 快报中同比/环比百分比统一保留1位小数（如6.79%显示6.8%、11.46%显示11.5%）；人次、车流等业务数值仍保留2位小数。
- **验证结果**：后端编译、前端构建、权限/CRUD/负向导入、历史变更两阶段导入、Excel 导出、Word 快报、前端 admin/非 admin 烟测均通过；菜单顺序、客运系数 2.4 展示（系统配置页 + 节假日统计页）、`decimal(30,15)` 列型、历史变更两阶段导入回归均已实测；功能测试报告与工作日结按 2026-09-27 提交规范仅本地留存（不入库）：`docs/功能测试报告/功能测试报告_重要节假日专项统计_2026-10-02.md`、`docs/工作日结/工作日结_2026-10-02.md`。