fix(holiday): 快报表格改用带符号百分比并保留模板样式

xyc

4 天以前 520bdcba17d90b07d7d63fdcdb0e98a2a0a87300

 HANDOFF.md

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

## 最新（2026-10-03）

### 10-03 晚：重要节假日新模板（2019/前一日）适配
- **模板变化**：`2026年十一数据.xlsx` 的道路表增加 2019 年及同比2019；铁路、民航增加“前一日”行；快报模板增加同比2024 列。旧模板已放在 `docs/专项统计/重要节假日/备份/`。
- **数据库初始化**：启动时直接写入 2019 道路数据，以及 2024/2025/2026 年铁路、民航前一日数据；`holiday_calendar.day_index=0` 表示“前一日”，旧库启动会自动补齐已有年份的前一日配置行，且不覆盖管理员已维护的日期。
- **正常导入口径**：只读取所选年份的当年列（2026 年铁路/民航/道路/水路为 C 列、高速为 C 列、普通国省道为 D 列）；同时只额外读取当前年份铁路/民航的“前一日”行。2019/2024/2025 历史列不参与导入。
- **快报口径**：同比只使用 2025、2024；假期第 1 日的铁路、民航环比使用“前一日”数据，公路、水路、总计及其他口径第 1 日仍显示“—”；第 2 日起正常计算环比。
- **迁移脚本**：`docs/sql_holiday_previous_day_migration.sql`，部署包同步为 `deploy-templates/db/sql_holiday_previous_day_migration.sql`，脚本可重复执行。
- **2019 显示补齐（10-03 晚追加）**：`holiday_calendar` 增加 2019-10-01 至 2019-10-08 配置；系统配置-节假日管理和专项统计-节假日均增加 2019 年份，历史库执行幂等迁移后即可查看 2019 年 8 天道路数据。
- **验证（本机 3305 库 + 真实模板）**：接口导入结果 `passengerRows=10, vehicleRows=4, successRows=14, failRows=0`；数据库抽查 2026-09-30 铁路=82.1、民航=6.6994，2026-10-01 铁路=113.8、民航=6.7482、道路=78.82、水路=1.311，2026-10-02 铁路=82.0、民航=6.3914、道路=75.61、水路=3.3373；2026-10-01 快报铁路环比=+38.6%、民航环比=+0.7%，总行环比为“—”；2026-10-02 铁路环比=-27.9%、民航环比=-5.3%。
- **运行状态**：后端 8090（重启后已加载新代码）、前端 8080 均在运行；访问 `http://localhost:8080`。

### 10-03 深夜：快报表格百分比与模板样式修复（已验收）
- **问题**：生成快报表格使用“增长/下降”文字，数字拆行并多出 1 页；复核发现模板路径正确，根因是 `HolidayBulletinService#setCellText` 替换单元格时只保留段落属性，未保留模板 run 的字体/字号属性。
- **口径**：表格环比/同比改为带符号一位小数（正数不加 `+`，负数保留 `-`），零或一位小数后为零显示 `0%`，缺失/基数为空或为零显示 `—`；正文继续使用“增长/下降”。
- **修复**：单元格替换时继承模板 `rPr`；新增 `HolidayBulletinServiceTest` 覆盖正数、负数、零、四舍五入为零、缺失和零基数。
- **验证**：Maven 编译和测试通过；重新生成 2026-10-01 快报，正文仍为“增长2.3%”且不含“增长了”；Word 导出由 2 页恢复为 1 页，数字不再拆行。最终样报见本地 `_tmp_holiday_verify/bulletin_final_signed_styled_2026-10-01.docx`。
- **状态**：2026-10-03 用户验收通过；本次提交只包含代码、回归测试和本交接记录，不包含 `_tmp_*` 过程产物及用户未提交的数据文件重命名。

---

### 补充（10-03 下午）：服务器部署报 “Access denied ... (using password: NO)” —— 根因与修复
- **现象**：把 `deploy/traffic-audit-release-20261002/` 部署到 `61.183.254.94` 后，后端启动报 `java.sql.SQLException: Access denied for user 'root'@'localhost' (using password: NO)`。
- **根因**：jar 内置配置里库口令是占位符 `${TRAFFIC_DB_PASSWORD:}`（默认空串），而 10-02 那个包**只含 jar + web + dist**，没有外置 `application.yml`、没有 `docs/`、`db/`、启动脚本。部署机没有任何外部配置覆盖，Spring 就拿空密码连本机 MySQL → `using password: NO`（注意：这是“末传密码”，不是密码错）。
- **服务器侧一步修复（无需重打包）**：在 jar 同级放 `application.yml`，把 `spring.datasource.url/username/password` 改成现场真实值后重启即可；也可用环境变量 `TRAFFIC_DB_PASSWORD` 代替。启动脚本已加预检提醒（缺 `application.yml` / password 仍是占位文字都会 WARN）。修复后若报“未找到数据目录 docs”则说明包内缺 `backend/docs`，从新包或源机器拷。
- **打包工具已修（原 “打包工具待修” 两项均已落实）**：`pack-deploy.ps1` 重写为五步：① 用新增模板 `deploy-templates/jar-application.yml`（**全占位符**）临时替换源码配置后 `mvn clean package`，无论成败都还原真实配置；② 解压 jar 去密自检；③ 前端构建；④ 组装**完整包**：`backend/{jar, application.yml, start-backend.cmd/.sh, docs/, web/}` + `frontend/dist` + `db/*.sql` + README（`backend/web` 从 dist 自动同步，逐文件一致）；⑤ 整包明文密钥扫描。新增 `-SkipBackend` 可复用现有 jar 快速重组包。
- **模板同步修正**：`deploy-templates/backend/application.yml` 的 `server.port` 由 8080 改回 8090（原值会导致后端起在 8080）、补 `static-locations: file:./web/` 与 password 陷阱注释；`README-部署说明.txt` 常见问题新增该报错处置；`docs/打包部署说明.md` 排错表新增该行；`application.yml.example` 环境变量名统一为 `TRAFFIC_DB_USER/TRAFFIC_DB_PASSWORD/TRAFFIC_JWT_SECRET`（原来误用 `MYSQL_PASSWORD`/`JWT_SECRET`，与 `start-dev.ps1` 不一致）。
- **新包（本地，不入库）**：`deploy/traffic-audit-deploy-20261003/`（388 文件 / 93.07 MB，zip 76.37 MB），已验证：jar 内置配置全占位符（去密自检通过）、`backend/web` 与 `frontend/dist` 逐文件一致（各 44 个）、`backend/docs/生成汇总大表` 母版存在、`功能测试报告/工作日结/问题汇总/_cache` 已排除。
- **踩坑（重要）**：本机 PowerShell 5.1 把无 BOM 的 `.ps1` 当 ANSI 读，中文注释会变成乱码并导致脚本解析失败。`pack-deploy.ps1` 必须保存为 **UTF-8 with BOM**（仓库其他 `*.ps1` 也都是 BOM）；排查中曾实际踩到。

- **运行状态（写交接时）**：后端 8090、前端 8080 均未监听；新对话如继续开发或测试，先执行 `powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`。数据库仍为 `127.0.0.1:3305/traffic_audit`，MySQL 服务未停。
- **发布构建（已完成）**：应“发布编译”要求，已完成后端 `mvn clean package -DskipTests` 和前端 `npm run build`。jar 内已做去密自检，只保留环境变量占位符；构建后本机真实 `src/main/resources/application.yml` 已原样恢复。
- **发布产物（本地，未入库）**：
  - 后端 jar：`traffic-audit-server/target/traffic-audit-server-1.0.0-SNAPSHOT.jar`（约 54.6 MB）
  - 前端：`traffic-audit-web/dist`（44 个文件、约 3.55 MB）
  - 发布目录：`deploy/traffic-audit-release-20261002/`（含 `backend/`、`frontend/dist/`）
  - 发布压缩包：`deploy/traffic-audit-release-20261002.zip`（约 51.11 MB）
- **发布包结构说明**：`frontend/dist` 是标准前端发布目录；`backend/web` 是同一份 dist 的副本，用于后端 8090 单端口模式（当前静态资源路径为 `file:./web/,classpath:/static/`）。两处已逐文件比对，文件列表与 SHA-256 完全一致。
- **安全状态**：本机真实配置已保存在被忽略的 `traffic-audit-server/config/application.yml`；发布 jar 不含真实数据库口令、JWT secret 或 DeepSeek key。发布包不包含部署机的真实外部配置，部署时需要继续使用现场 `application.yml` 或按模板填写。
- **打包工具待修（重要）**：`pack-deploy.ps1` 目前直接消费 `src/main/resources/application.yml`，若该文件被本机真实配置覆盖，会在去密自检阶段中止；且它只把 dist 放到 `frontend/dist`，没有同步到 `backend/web`，默认包无法直接用于 8090 单端口模式。本次使用“临时占位符配置 → 构建自检 → 恢复真实配置”的方式完成。下次发布前建议改为从 `application.yml.example` 生成临时资源，并在组装阶段同时复制 `backend/web`。
- **Git/工作区（本段更新前）**：`HEAD = origin/main = 37f5209`；当前无已跟踪文件改动。未跟踪项有 `_tmp_holiday_verify/`（历史验证产物）和 `docs.zip`（约 31.6 MB，用户本地产物）；二者均保留，新对话不要误删或误提交。
- **下一步**：如需部署，直接使用上面发布目录或 zip；如需继续修复发布工具，先实现“占位符模板自动切换 + `backend/web` 自动组装 + jar 去密自检”后再重新产出发布包。

### Windows 开机自启（10-03 追加，用户选“方案 B”：注册成 Windows 服务）
- **先回答过的问题**：`start-backend.cmd` **不能**直接做开机自启（末尾有 `pause`、无日志重定向、依赖 PATH）。给出 A（计划任务）/B（Windows 服务）/C 三方案后，用户选 **B**。
- **新增模板（已入库）**：
  - `deploy-templates/backend/trafficAudit.xml`：WinSW 服务配置——id `TrafficAuditBackend`、`startmode=Automatic` + `delayedAutoStart=true`（等 MySQL 先就绪）、`onfailure restart 10s/30s/60s` + `resetfailure 1 hour`、`workingdirectory=%BASE%`、日志 `logs\trafficAudit.out.log|err.log`（10MB × 10 滚动）。
  - `deploy-templates/backend/install-service.ps1`：管理员安装/查看/重启/删除（`-Status/-Restart/-Remove/-NoStart/-JavaPath`）；自动定位 java（JAVA_HOME → PATH → JavaSoft 注册表 → Program Files）并把绝对路径写进 XML 的 `executable` 元素；重复执行幂等；非管理员直接拒绝。
  - `start-backend-service.cmd` + `install-autostart.ps1`（计划任务方式）保留为**备选**；注意 `New-ScheduledTask*` 需 Win8/Server 2012+，且**不可与服务方式同时启用**（会抢 8090）。
  - `pack-deploy.ps1`：新增 WinSW 获取（缓存 `deploy-templates/tools/winsw.exe` 并校 SHA-256，缺则从 GitHub 下载 v2.12.0 x64）与 `-SkipServiceWrapper`；包内输出 `backend\trafficAudit.exe`（改名以匹配 XML 文件名）。`.gitignore` 新增 `deploy-templates/tools/`（17.4MB 二进制不入库）。
- **WinSW = Windows Service Wrapper**：把普通程序包成 Windows 服务。java.exe 自己不是服务程序，直接 `sc create` 会报“服务没有及时响应启动或控制请求”；WinSW 实现了服务控制协议再拉起 `java -jar`，并管重启与日志。
- **实测验证（本机，未真正安装服务）**：`trafficAudit.exe status` 能读打包 XML 并输出 `NonExistent`（解析通过）；故意写坏 XML → `FATAL - The configuration file cound not be loaded`（证明该校验路径真实有效）；`install-service.ps1 -Status` 正常输出“未安装”，无参数 / `-Remove` 在非管理员下抛“必须管理员”且不产生注册项。
- **踩坑（重要）**：XML 改写最初用正则 `(?s)<executable>.*?</executable>`，会**先命中注释里的 `<executable>` 字样**，把注释头与 service 开头整段吞掉 → XML 非法。已改为 DOM（`SelectSingleNode('/service/executable')`）并把注释里的裸标签改掉。另：新增打包代码曾多一个 `}` 导致语法错，已用 `Parser::ParseFile` AST 复核，两个 ps1 现在语法 OK 且均为 UTF-8 with BOM。
- **兼容性（用户问“Win7/Win10/Win11/Server 是不是都可以”）**：服务机制完全一样（自动启动/延迟启动/失败重启都是系统能力），差别只在包装器依赖什么运行时。实测二进制：`WinSW-x64.exe` 2.12.0 是**自包含 .NET 6 单文件**（含 `singlefilehost`/`System.Private.CoreLib`/`Microsoft.NETCore.App 6.0.13`/`net6.0`），**不需要装 .NET Framework**；老系统（Win7 SP1/2008R2/2012R2）若报 `api-ms-win-*.dll` 缺失，可换官方 `WinSW.NET461.exe`（0.6MB，需 .NET 4.6.1+，改名成 `trafficAudit.exe` 即可，XML 不动）；32 位系统换 `WinSW-x86.exe`。
- **安全提示**：WinSW 官方产物**未做 Authenticode 签名**（本机 `Get-AuthenticodeSignature` = NotSigned），因此以固定 SHA-256 作完整性校验：`05B82D46AD331CC16BDC00DE5C6332C1EF818DF8CEEFCD49C726553209B3A0DA`（与 GitHub 发布资产 18,243,033 字节一致）。
- **未验证项（需在目标机做一次）**：本机当前不是管理员，**没真正 install 过服务**；开机自启、失败重启、日志滚动要在服务器上按 README 3.1 执行一次确认。
- **新包（本地，不入库）**：`deploy/traffic-audit-deploy-20261003-3/`（393 文件 / 110.49 MB，zip 83.77 MB）。已验证：服务三件套在 `backend\`、包内 `trafficAudit.exe` SHA-256 与固定值一致、`backend\web` 与 `frontend/dist` 各 44 文件、jar 去密自检通过、无明文 key。**旧的 `traffic-audit-deploy-20261003/` 与 `-2/` 已被取代**，部署请用 `-3`（旧包待用户确认后再删）。
- **运行状态（写本条时）**：开发用后端 8090（PID 43040）、前端 8080（PID 43152）均在跑；数据库 `127.0.0.1:3305/traffic_audit`。
- **补充可操作性（用户反馈“backend 下文件太多，不知道怎么操作”）**：
  - 新增双击入口 `deploy-templates/backend/install-service.cmd`：自动 UAC 提权 → 调 `install-service.ps1`；若找不到 `trafficAudit.exe` 则提示“必须整个 backend 一起拷”。
  - `install-service.ps1` 装完会自己探测端口（TCP 探测，兼容 PowerShell 2.0），打印 OK + 本机/对外网址；起不来时直接打印 `logs\*.log` 最后 15 行；若 `application.yml` 口令仍像占位符，最后再打一次醒目提示。
  - `README-部署说明.txt` 顶部新增【服务器上只要做这 3 步】+“哪些要拷/哪些不用拷”；`docs/打包部署说明.md` 的 5.4 改为“右键 `install-service.cmd` →以管理员运行”。
  - 三个 `.cmd` 模板统一为 CRLF（新增的两个原来是 LF，批处理在 Windows 上应用 CRLF）。
  - 实测：强制走“已提权”分支时 `cmd → install-service.ps1 -Status` 链路跑通、`%*` 传参正常；`Test-LocalPort` 对 8090 返回 True、对 8099 返回 False。
  - 新包：`deploy/traffic-audit-deploy-20261003-4/`（394 文件 / 110.50 MB，zip 83.78 MB）——**当前唯一可用包**。
- **发布包清理（10-03 晚，用户确认“只留 -4”）**：已删除 `traffic-audit-release-20261002/`(+zip)、`traffic-audit-deploy-20261003/`(+zip)、`-2/`(+zip)、`-3/`(+zip) 及空的 `server-fix/`，`deploy\` 现在只有 `traffic-audit-deploy-20261003-4/` 和它的 zip（释放约 671MB）。
  > 因此本文件上面提到的 `deploy/traffic-audit-deploy-20261003/`（388 文件）与 `deploy/traffic-audit-release-20261002/` 均为**历史记录**，磁盘上已不存在，别再去找。
- **紧急修复（10-03 晚）：`install-service.ps1` 密码解析崩溃，服务根本没装上**
  - 现象：用户在服务器（`D:\trafficAudit`）双击 `install-service.cmd`，报 `无法将“Trim”的参数“trimChars”转换为类型“System.Char”`，位置 `install-service.ps1:210`。
  - 根因：那行是 `.Trim(' ''', '"')`，其中 `' '''` 被 PowerShell 解析成一个**长度 2 的字符串**（空格 + 单引号），`Trim(char[])` 无法把 2 字符串转成单个 char → 整行抛异常（`MethodArgumentConversionInvalidCastArgument`）。
  - 修复：把这段抽成纯函数 `Test-AppConfigPassword`，改写为 `Trim()` → `Trim("'")` → `Trim('"')`；并加脚本级 `trap`，任何异常只打印一行说明 + 行号，不再甩红字堆栈。
  - 验证：8 个样本（缺文件 / 空值 / 中文占位符 / 裸值 / 双引号 / 单引号 / 含空格特殊字符 / 真实模板文件）全部符合预期；打包内脚本语法解析通过、`-Status` 实跑正常、非管理员时 trap 输出干净错误并 exit 1。
  - 教训：这条分支之前没被任何测试覆盖（`-Status` 提前 exit、非管理员在 `Assert-Admin` 就退出），所以解析类逻辑要抽成纯函数并用样本测。
  - 包名：修复版重打包时脚本复用了已释放的基础名，最终已删掉旧坏包并改名，`deploy\` 仍然是**唯一**的 `traffic-audit-deploy-20261003-4\`（含修复后的 install-service.ps1）与同名 zip。
  - 用户侧最小修复：只需用新包里的 `backend\install-service.ps1` 覆盖服务器 `D:\trafficAudit\install-service.ps1`，再重跑 `install-service.cmd`（不必重拷 110MB）。
- **服务器部署成功（10-03 晚，用户确认）**：服务器（部署目录 `D:\trafficAudit`，把 backend 里的内容直接铺在该目录下）用修复后的 `install-service.cmd` 安装服务 `TrafficAuditBackend` 成功。
  - **已验证（用户确认）**：① 办公电脑浏览器能打开服务器页面（说明网络/防火墙这一层通，无需额外放行 8090）；② **重启服务器后仍能从办公电脑打开页面 → 开机自启实测生效**（服务不依赖任何账号登录）。
  - **仍待做**：业务功能验收（登录 / 数据导入 / 报表导出 / Word 快报）；确认 `application.yml` 的 jwt.secret 已换成正式随机值、预置 admin/admin123 已改密。
  - 防火墙放行（老系统也能用）：`netsh advfirewall firewall add rule name="TrafficAudit 8090" dir=in action=allow protocol=TCP localport=8090`
  - 装完后常用：`install-service.ps1 -Status / -Restart / -Remove`；日志在 `D:\trafficAudit\logs\trafficAudit.out.log`（错误看 `trafficAudit.err.log`）。

## 最新（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)` 列型、历史变更两阶段导入回归均已实测；功能测试报告与工作日结按 2026-09-27 提交规范仅本地留存（不入库）：`docs/功能测试报告/功能测试报告_重要节假日专项统计_2026-10-02.md`、`docs/工作日结/工作日结_2026-10-02.md`。
- **运行状态**：后端 8090、前端 8080 已启动；数据库 `127.0.0.1:3305/traffic_audit`。测试产生的 2026 临时数据和导入批次已清理。
- **关机收尾（2026-10-02）**：已停掉本次开发用后端 8090、前端 8080 及各自进程树，端口均已释放；MySQL 服务保留。当前可安全关机。
- **Git**：用户已于 2026-10-02 明确验收通过；本次按要求合并远端 `origin/main` 后提交并推送，不覆盖远端同事提交。
- **部署模板同步**：节假日 4 张表已同步到 `deploy-templates/db/init.sql`；`sql_holiday.sql` 及两个旧库迁移脚本随部署包发布，避免新包缺表。

## 最新（2026-09-28）

- **用户用 WPS 编辑母版**：改《班线包车》边框、《道路运输周转量》字号，并删除《中口径明细》`AW` 列（手工定稿同删）。已验证生成端正常：中口径明细 2024 及更早块整体左移（跨页/同页公式自动改引用，`#REF!` 2→0）、中口径排名块 J..R → A..I 均正确带入产物。
- **⚠️ WPS 保存的连带损坏（待回补）**：《班线包车》2019/2020 块约 **590 格**内容丢失（`FN/FO/FM`、`FP:FT`、`GE` 变空；`EO/EQ/ES/EU/EW/EY/DT/DW...EM` 共 **144 格**变 `#DIV/0!`）。生成件已带出（该页 `#DIV/0!` 228→372）。**待用户确认后按备份/定稿回补（只补值与公式，保留其边框与字号）。**
- **口径落地「缺数留空」**：母版《 货运》行 90/93（仙桃 规上两行）、108/111（林区）在 2021、2022 年块的 78 个 `0` 值已清空（与手工定稿按表头对齐逐格核对：母版=0 且定稿=空 78 格、冲突 0 格）；代码 `FreightCalc.buildMetrics` 当月分支改为「该月无规上记录 → 留空」，不再写 0（累计分支不变）。
- **纠正一条错判**：此前「程序少一列 11 月环比」不成立——生成件与手工定稿的环比期间集合完全一致（12月…1月 共 12 列）；差异根因是手工定稿《 货运》在 2025 年块多一列**无表头辅助列**（`U`，74 格），自该列起手工整体右移 1 列。**比对必须按表头期间对齐，不能按列位置比。**
- **验证**：生成两次（约 15 秒/次），第二次相对第一次**仅 78 格 0→空**，错误值数量不变；`公交!S5=98460.97` 等缓存值抽查保留。
- **运行状态**：后端已按 `start-dev.ps1` 重启（新 PID，8090/8080 在跑）；本机库仍为 `localhost:3308/traffic_audit`。
- **✅ 班线包车回补完成（09-28 下午）**：用户确认后按 09-27 母版备份（`_bak_202608母版文本数字转数值前_20260927.xlsx`）XML 精准回补《班线包车》2019/2020 块 —— **该页与 09-27 母版逐格一致（0 差异）**，错误值回到 `#REF!` 8 / `#DIV/0!` 228；母版其它页未受影响。验收生成：与 09-27 生成件 (6) 比对错误值逐页一致，差异仅剩既定改动（` 货运` 78 格清 0、中口径明细 4915 格删列位移、中口径排名 672 格块位移、班线包车 82 格浮点尾差/0-空）。
- **差异清单口径更新（09-28，用户确认）**：① ` 货运` 新增的「规上+规下货运量」「规下货运量」各 17 行（母版设计，共 34 行）不计差异；② ` 货运!U5:U112` 无表头草稿列不计；③ 排名表「当月块」为母版设计不计；④ 市州短名/全名不影响（工具归一化）；⑤ 小差异（取整尾差/文本型数字）只计数，只列差异大的并附原因。工具 `docs/工具/汇总大表差异比对.py` 已按此更新，两份清单已重生成。
- **新发现（待核对）**：`班线包车!EO36/FN36/FO36`（荆门 客运量 2020 累计/累计同比）**程序生成时重算为 -2731.41 / -1.0008 / -1.0002**，而母版与手工定稿均为 0.181777 / 2312.2199 / -0.586419 → 疑母版 2020 年块分母为 0，需核对公式与数据。
- **汇总大表差异比对（09-28，工具已固化口径）**：`docs/工具/汇总大表差异比对.py`（逐页按行/列标签序列对齐，可处理多列/多行/重复表头）。**清单属过程产物只留本地**（`docs/问题汇总/_清单_*.md/.csv`，已 gitignore 不入库）。
  - 已确认口径（不再重复确认/上报）：① 货运每市州 6 行 vs 手工 4 行（新增「规上+规下货运量」「规下货运量」各 17 行）属母版设计，行号偏移按"地区+指标"对齐后一致；② ` 货运` U 列（U2:U118）为人工草稿；③ 仅手工有且**无表头**的列 = 草稿；④ 浮点尾差、文本型数字忽略；⑤ 排名表「当月块」为母版设计；⑥ 市州短名/全名不影响。
  - **需处理（数值）**：`班线包车!EO36/FN36/FO36`（荆门 客运量 2020 累计/累计同比）——程序生成时重算为 -2731.41 / -1.0008 / -1.0002，母版与手工定稿均为 0.181777 / 2312.2199 / -0.586419（疑母版 2020 年块分母为 0），待核对；` 货运` 2022 年各市州「累计同比」10 条（业务已确认**软件对**，不改）。
  - 其余待办：手工侧 4 处脏数据（`班线包车!IL4/IL5` 断链、`IL50` 反引号、` 货运!EA93/EA111` 的 `#DIV/0!`）、286 格文本型数字、304 格草稿列；母版 11 个 `#REF!` + 356 个 `#DIV/0!`；`城市客运` 第 2 行第 3 个月起表头为日期序列号；缺 2026-09 母版；导出前基数体检（P0-3）。
- **09-28 收尾：`班线包车` 3 格重算问题已修**：`EO36`/`FN36`/`FO36` 在母版里改为**静态值**（0.181777001400256 / 2312.2199 / -0.586418964965219，与手工定稿一致），并把受影响的共享公式组孤儿子格（35 格）一并静态化（值零变化）。重新生成验证：生成件/母版/定稿三边一致，与上一版生成件仅 34 格为精度表示差异、无数值变化。
- **当前"需处理"仅剩 16 条**（均属手工侧/业务已确认，非程序问题）：` 货运` EA92~EA112 共 12 条（2022 各市州累计同比，2021 年基数口径不同，业务已确认软件对；含手工 `#DIV/0!` 2 条）、`班线包车` IL4/IL5（手工 `#REF!`）/IL50（手工反引号）3 条、`城市汇总!G20` 表头措辞 1 条。其余全部按口径忽略（草稿列/行号偏移/当月块/浮点尾差/文本型数字）。
- **未清项（有意保留）**：母版 11 个 `#REF!` + 356 个 `#DIV/0!` 历史错误值未清——手工定稿同类约 15 + 358，单清一边会凭空多出单边差异；要清需两边一起。
- **确认差异清单（本地）**：`docs/问题汇总/_已确认差异清单_2026-08_20260928.md`（不入库）。
- **09-28 口径全部落地，差异清单"需处理"归零**：
  - ① 按软件：手工定稿《 货运》EB64~EB78 等 12 格 2022 累计同比 + 《班线包车》IL4/IL5/IL50 已按软件值同步（备份 `2026年8月客运量、货运量定稿_同步软件前_20260928.xlsx`）。
  - ② 按手工统一措辞：母版《城市汇总!G20》改为手工写法"2025年1-12月全省累计完成城市客运量情况"（备份 `_bak_202608母版_0928措辞前.xlsx`）。
  - ③ 历史错误值留白：母版 363 格（`_bak_202608母版_0928留白前.xlsx`）、手工定稿 379 + 尾列 6 格（`..._留白尾列前_20260928.xlsx`）→ 两边现均为 0 个 `#REF!`/`#DIV/0!`。
  - 结果：按当前母版重新生成 2026-08 后，与手工定稿的**需处理差异 = 0**，其余全部落在"已忽略（约定差异）"。清单：`docs/问题汇总/_清单_母版最新生成件_20260928.md/.csv`（本地，不入库）。
  - 注意：桌面那份 `生成_道路运输量汇总表_2026-08.xlsx` 是旧导出（含旧错误值/旧基数），与更新后的定稿比对会显示较多差异，以"母版重新生成件"为准。
- **无表头草稿列清单（9 处，共 539 格）**：`公交/出租/网约车!U`（各 72）、`城市客运!U`（36）、`班线包车!DU`（55，表头"1-3月累计"）、`中口径明细!U`（90）、`中口径客运量!AB`（180）、` 货运!V` 与 ` 货运!AX`（各 74，用户所指 U 列在手工那份右移一列）。母版/生成件**已全部清空**，手工定稿仍保留 → 对比时归入「已知设计(无表头草稿列)」。其余"无表头列"是合并表头的正常列（` 货运!C…Q` 月份值列、各年块尾部累计/累计同比列、排名页 R 列等），两边都有、非草稿。明细见 `docs/问题汇总/_已确认差异清单_2026-08_20260928.md`。
- **待办**：① 排名页结构（块顺序、标题措辞、市州名短名/全名、周转量排名多 7 行）；② 排名页结构（块顺序、标题措辞、市州名短名/全名、周转量排名多 7 行）；③ 缺 2026-09 母版、导出前基数体检（P0-3）。

## 最新（2026-09-27）

- **提交规范改为同事方式（用户 09-27 决定，已写入 AGENTS.md）**：
@@ -34,6 +162,11 @@
        · **表头措辞修复（按人工定稿为准）**：`轨道、轮渡!R2`、`R11` 由母版自带的"8月与去年同比"改为"同比"（与该页 `T2/T11`"累计同比"体例一致、与手工定稿一致；程序不写这两格，故只改母版）。
          验证：重新生成 2026-08 → 新旧生成件逐格比对 **仅这 2 格文字变化，19 页签与尺寸不变、其它一律不动**。
        · **判定为"程序正确、不改"的两处**：① `道路运输周转量!A23` 程序"2026年8月全省完成交通周转量情况"（该块是**当月值**：全省 2,301,720 vs 累计块 17,749,657 万吨公里）→ 手工定稿多写了"累计"；② ` 货运!EA92:EA112` 2022 年累计同比 10 条（业务已确认软件口径正确）。
        · **文本型数字统一为数值（用户口径"按程序对的改"）**：母版 157 格文本型数字 → 数值（`公交` 153 = AF 68 + M 68 + G 17；`轨道、轮渡` 4 = M 2 + E 2），仍用 XML 精准改类型（缓存值全部保留）。重新生成 2026-08 → 与上一版比对：**仅 68 格类型变化（str→数值、数值相同），无任何值/尺寸变化**（其余 89 格程序本就会写数值）。注：比对里另有 286 条"文本型数字"差异在**手工定稿侧**（手工存文本），需手工侧统一或忽略。
        · **排名页"两个块顺序对调"（实为顺序问题，不是多了一张表）**：程序 以模板 `docs/货运/生成_货运量排名.xlsx`（模板本身=累计块在行1、当月块在行23）填充 → `货运量排名` 程序=行1累计/行22当月，手工=行1当月（"2026年8月各市州货运量排名"）/行22累计；`货运周转量排名` 程序 44×18（累计在前）vs 手工 51×18（当月在前、且多 7 行待细看）。**用户口径：手工为准** → 需改模板（两块对调）+ 相应代码（块定位/标题写法 `ReportExportService:961-966/1315/1575-1583`）+ 市州名由 `RegionUtil.shortName()` 改全名；估 0.5~1 天含回归，待开工。
        · **手工多出的"辅助列"清单**：` 货运` 多 1 列（无表头，位于"同比"之后、2025 年 1 月之前 → 实为 `U` 列"2025 年 1-8 月累计"辅助列，74 格，从 V 列起手工整体右移）；`城市客运` 多 `AJ`="2025年1-7月累计"（母版 09-20 已删、程序已不输出）；`班线包车` 多 `DU`="1-3月累计"（即本次清空的草稿列）；`道路运输周转量` 末尾多 2 列（Z/AA，**表头与内容均为空**）。
        · 取整尾差 194 条：用户明确"不用管"。

        · **仍待业务定的版式/措辞项**：`货运量排名`/`货运周转量排名` 的标题、表头（程序"累计完成(万吨)" vs 手工"规上货运量(万吨）"）与市州名（程序按设计用短名"武汉/恩施/林区"、手工用"武汉市"等全名）——需业务确认以哪版为准。

        · ⚠ **待同事确认**：手工定稿侧也把这些草稿列留空，否则比对会从"程序有值/手工有值"变成"程序空/手工有值"（同类差异、方向相反）。