feat(节假日): 新增重要节假日专项统计模块

xyc

4 小时以前 b509d59af23c6afba086fa3fb4c2afb47ab0becb

 HANDOFF.md

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

## 最新（2026-10-02）

- **新模块（用户已验收，本次提交/推送）**：新增“专项统计-重要节假日”模块，含节假日配置、营业性客流、非营业性车流、客运系数 4 张表；系统配置菜单仅 admin 可维护，专项统计-节假日支持导入、导出、模板下载和 Word 快报下载。
- **数据初始化**：从 `docs/专项统计/重要节假日/2026年十一数据.xlsx` 初始化 2024/2025 年十一客流、车流和 2024-2026 年客运系数；源表 90 个数据单元格入库逐项比对差异 0。
- **日常导入口径**：只读取所选年份的当年列（2026 年为各客流工作表 C 列、普通国省道 D 列）；历史年份不要求日常重导。
- **历史数据保护**：导入时先检查更早历史日期是否被修改。有变化则先不写库，返回差异清单，前端弹窗让用户选择“允许导入/不允许”；确认后才覆盖。接口参数 `allowHistoricalOverwrite=true`。
- **快报**：默认下载系统日期前一天的《湖北省国庆假期综合运输客流快报（10月X日）.docx》，用户可自选日期；环比/同比按增长、下降、持平输出。
- **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 追加）**：假期第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)` 列型、历史变更两阶段导入回归均已实测；报告见 `docs/功能测试报告/功能测试报告_重要节假日专项统计_2026-10-02.md`，日结见 `docs/工作日结/工作日结_2026-10-02.md`。
- **运行状态**：后端 8090、前端 8080 已启动；数据库 `127.0.0.1:3305/traffic_audit`。测试产生的 2026 临时数据和导入批次已清理。
- **Git**：用户已于 2026-10-02 明确验收通过；本次按要求合并远端 `origin/main` 后提交并推送，不覆盖远端同事提交。

## 最新（2026-09-23）

- **已同步**：本地 `main` 快进合并公司 `origin/main` 最新 `8b739ce`（同事 09-22 关机快照统一版），合并后 `HEAD = 8b739ce = origin/main`，工作区干净。
- **本次新增交接文档**：`docs/交接文档_2026-09-23.md`（09-23 增量：现状快照 + 腾讯文档读取调研 + 当前待办 + 文件索引）。系统全景与 P0/P1/P2 全量遗留仍以 `docs/交接文档_2026-09-21.md` 为准。
- **今日工作**：腾讯文档读取调研 + 潜江物流投资月报重导修正；无业务代码改动（见 `docs/工作日结/工作日结_2026-09-23.md`）。
- **潜江重导（已完成）**：潜江物流 2026-06/07/08 在应用实际库 `3305` 均改为“中国虾谷冷链仓储物流园” `11947.9 / 0 / 1135 / 0`；重复重导保持每月 1 条、无重名项目，2026-08 导出端到端核对通过。09-22 报告记录的验证库是 `3308`，与当前应用连接库不一致，故当前库 08 月旧值本次一并修正。报告 `docs/功能测试报告/功能测试报告_潜江投资物流月报重导_2026-09-23.md`。
- **腾讯文档读取调研（新结论）**：
  1. 只读分享链接（《2026年十一数据》，10 页签）**能读显示值** —— 浏览器「打印 → 整个工作簿 → 打印预览」渲染成 SVG 段，读 `<text>` 即得数值/日期/百分比/`#DIV/0!`；但读不到公式、隐藏行列、打印范围外内容，且不易恢复精确 A1 坐标。
  2. **trafficAudit 目前不支持**在线文档导入，只走本地文件上传（`DataImport.vue:57/502` → `DataImportController.java:33` → Apache POI）。
  3. **腾讯官方 Open API V3 可行**：`GET /openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}`（A1 范围，返回 `cellValue`），但需 OAuth 2.0 + 应用凭证 + `scope.sheet(.readonly)`；仅凭分享链接不能匿名调用。落产品建议走官方 API，不用打印预览。详见 `docs/交接文档_2026-09-23.md` §3。
- **运行状态（09-23 08:50 续接实测）**：dev 后端 `8090`、前端 `8080` 已启动并就绪，应用数据库 `localhost:3305/traffic_audit`。启动命令：`powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`（沙箱外）。
- **接手优先（更新）**：投资明细表 L/D/E/F 覆盖口径、武汉物流/黄冈客运 8 月源数据、未覆盖清单落文件；汇总大表 304 格「2025 累计列」；P0-2 亿元表按 Q7 追列、P0-3 导出前基数体检、P0-4 2026-09 母版。

## 最新（2026-09-22）

- **已同步**：本地 `main` 已快进到公司 `origin/main` 最新 `a08817b`（数据查看按市州汇总/导出、汇总大表结果落盘缓存等）。
- **已同步**：本地 `main` 已合并公司 `origin/main` 最新 `db0ee92`（含投资明细取数/导入修复）；合并后 `mvn -q -DskipTests compile` 通过。
- **Codex 输入卡顿复核（已完成）**：电脑与 Codex 于 09-22 12:54 重启后，`Codex++` 修复脚本仍启用；主渲染进程空闲 CPU 约 13.3%（单核），调试守卫 `installed=true`、本次会话 `dropped=16`。对比修复前约 115%，卡顿问题已解决。
- **今日已完成（远端提交）**：数据查看补齐网约车/个体客运、按市州汇总与导出 Excel、汇总大表进度弹窗与结果落盘缓存。
- **汇总大表差异复核（2026-09-22）**：软件输出与手工定稿经 Excel 全量重算后逐格比对，930 条差异中实质数值差异 314 条；其中 304 条为 2025 累计列少加 7、8 月（业务已确认可清空），10 条 ` 货运` 历史同比业务已确认软件正确。报告见 `docs/问题汇总/汇总大表_软件输出与手工定稿差异清单_2026-08_20260922.md`，明细见同名目录 CSV。
@@ -39,6 +69,23 @@
  建议跑一次 2026-08 导出核对后再改文档。
- **入口**：`HANDOFF.md`（本文件）→ `AGENTS.md` → `docs/交接文档_2026-09-21.md` 第 4 章（P0/P1/P2 全量遗留）。

### 关机交接快照（2026-09-22 晚）

- **今日交付（两项，均已推送）**：
  1. 《投资明细表 软件生成 vs 人工版》逐格比对（156 格差异）+ 根因定位 —— `docs/功能测试报告/数据比对报告_投资明细表软件生成与人工版_2026-09-22.md`；
  2. 第一轮取数修复（导出 3 处 + 导入 2 处，含新发现的"潜江导入 2018 年历史 sheet"）—— `docs/功能测试报告/功能测试报告_投资明细表取数修复_2026-09-22.md`；回归后逐格差异 **156 → 129**，无新增差异。
- **git**：`main` = `db0ee92`，已同步公司 `origin/main`（已合并同事 `13c2d36` 汇总大表差异复核）。工作区干净；仅本地未跟踪的临时产物（`_tmp_diff_tables_0922.md`、`_tmp/gen_new_0922/`、`_tmp_*_0922.*`）和用户自己的 `docs/确认.docx` 未入库。
- **运行状态（17:2x 实测）**：dev 后端 `8090`、前端 `8080` **均在运行**（HTTP 200；后端为本次修复后的构建，16:43 经 `start-dev.ps1` 重启）；关机后自然停止、不需手工处理。数据库 `3308`（本项目）与 `3305/3306` 按惯例保留，数据已持久化。
- **下次启动**：项目根目录 `powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`（脚本会跳过已在跑的端口；前后端需在沙箱外运行）。
- **保留产物（未经确认不删）**：汇总大表 930 条差异报告/CSV、投资比对与修复报告、`_tmp*_0922.*`、`_tmp/gen_new_0922/`。
- **本轮数据变更**：仅重导修正 `investment_monthly` 天门、潜江 2026-08 两处数值，未删除任何项目主档、未动其他市州/期间。
- **接手优先（明日）**：
  1. L/D/E/F 列覆盖口径（需先确认《建设阶段归一表》：源表 主体施工/竣工收尾/未开工/本年正式施工/暂停施工/前期 → 输出用词）；
  2. 补源数据：武汉物流 8 月无单表、黄冈客运 8 月无源文件（导出已能自动告警，共 15 行受影响）；
  3. 潜江 2026-06 / 2026-07 月度仍是 2018 历史 sheet 错值，**用 6/7 月源表**重导（不要用 8 月文件重导）；
  4. 「未覆盖行清单」目前只进 `backend.log`，按 P1-9 可再做成《校验报错_<年月>.xlsx》或页面提示；
  5. 既有 P0/P1 不变（亿元表按 Q7 追列、导出前基数体检、2026-09 母版等，见 `docs/交接文档_2026-09-21.md` 第 4 章）。

## 最新（2026-09-21）

- **最新总入口**：`docs/交接文档_2026-09-21.md`（系统现状、P0/P1/P2 遗留、操作手册）；汇总大表专项见 `docs/问题汇总/汇总大表问题交接_2026-09-21.md`。