| | |
|---|
| | | > **每天结束时**：把当天进展、踩过的坑、新需求、未完成事项更新到本文件，然后可以放心开新对话。 |
|---|
| | | > **协作约定（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 深夜（2）：缺当日民航数据时的累计同比对比期间修正 |
|---|
| | | - **快报民航累计同比对比期间修正（2026-10-03，缺当日民航数据场景）**：当某运输方式当年累计覆盖的日期短于所选日期（典型为 10 月 2 日民航数据未出、民航累计只有 10-01），累计同比改为「只和往年已经覆盖到的日期比较」——先找当年最后一个有该指标数据的日期，再取往年同日累计。修复后缺失民航的 10 月 2 日快报民航累计同比由 `-50.5%/-49.9%` 变为 `-10.0%/-0.9%`（与手工稿 -10.03%/-0.87% 的 1 位小数值一致）。实现见 `HolidayBulletinService.comparableCumulative`（仅作用于民航行），其余行与总人员流动量口径不变。 |
|---|
| | | - **「累计同比 -4.65% vs 快报 -4.6%」结论（2026-10-03，无需改代码）**：Excel 显示的 -4.65% 是**两位小数**结果；底层精确比值是 `-4.64633%`（2026 累计 3082.23818、2025 累计 3232.42742），**一次四舍五入到 1 位小数就是 -4.6%**。把已经取到两位小数的 -4.65 再取一位才得到 -4.7，属二次取整，不采用。同理 2026 对 2024 为 `-1.7710%` → `-1.8%`。快报百分比统一 1 位小数口径不变。 |
|---|
| | | - **「暂缺民航」提示**：用户确认由人工在生成的快报稿上修改，系统不生成该提示行，**不做代码改动**。 |
|---|
| | | - **验证**：`HolidayBulletinServiceTest` 3 个用例通过（新增 2 个覆盖民航累计对比期间与无数据返回 null）；端到端用库内真实 2026-10-02 数据（铁路/道路/水路/车流齐全、缺民航）重新生成快报，民航累计同比 `-10.0%/-0.9%`、民航累计 `6.75`、总计累计 `3082.24`、总计累计同比 `-4.6%/-1.8%`，与手工稿口径一致。 |
|---|
| | | - **Git**：本次改动待用户「验收通过」后再提交/推送。 |
|---|
| | | |
|---|
| | | ### 10-03 深夜（3）：快报累计正文单位由「亿人次」改「万人次」（待验收） |
|---|
| | | |
|---|
| | | - **口径（用户/领导确认）**：假期累计数值目前偏小（0.31 亿），正文可读性差，改为与当日一致的**万人次**；例如 `假期以来，全省全社会跨区域人员流动量累计3088.63万人次`，不再输出「0.31亿人次」。表格与其余口径不变。 |
|---|
| | | - **实现**：`HolidayBulletinService` 抽出 `cumulativeParagraph(...)`，直接按万人次（2 位小数）输出累计值；同比仍为「增长/下降 + 一位小数」，**保持一次取整不变**（总计累计同比 2025 精确 -4.4486% → `-4.4%`；手工稿的 -4.5% 属二次取整，不采用）。 |
|---|
| | | - **验证**：`HolidayBulletinServiceTest` 4 个用例通过（新增 `cumulativeParagraphUsesWanUnitAndSingleRounding` 固化「万人次 + 一次取整」）；重启后端后重新生成 2026-10-02 快报，正文为 `累计3088.63万人次，比2025年同期下降4.4%，比2024年同期下降1.6%`，与手工稿仅差既定的取整口径；2026-10-01 回归正常（`累计1643.17万人次`）。 |
|---|
| | | - **状态**：待用户「验收通过」后提交/推送。 |
|---|
| | | |
|---|
| | | ### 10-03 晚（4）：新增「观测站分日调查数据」原始数据导入（待验收） |
|---|
| | | - **背景（用户 2026-10-03 提出）**：普通国省道车流量的来源之一是观测站分日调查数据（模板 `docs/专项统计/重要节假日/观测站分日调查数据 (2026年10月1日).xls`，其中字段「中小客流量」即普通国省道车流量来源）。**系统内不做关联**，节假日统计仍走原有导入；本功能只做原始数据留存，为后续分析挖掘积累数据基础。 |
|---|
| | | - **数据表**：新增 `observation_station_flow`，DDL 见 `docs/sql_observation_station.sql`，部署包同步为 `deploy-templates/db/sql_observation_station.sql`。保留模板全部 26 列（观测站编号/名称/观测里程/地市/区县/行驶方向 + 各车型流量 + 客车/货车/汽车/机动车流量 + 各类当量 + 机动车速度 + 拥挤度 + 来源文件名）。唯一键 `(obs_date, station_code, direction)`；**数值列一律 `DECIMAL(30,15)`**，Java 实体字段一律 `BigDecimal`，与节假日表同口径，无 float/double。 |
|---|
| | | - **导入实现**：新增包 `com.trafficaudit.observation`（entity / mapper / dto / service / controller）。用 POI `WorkbookFactory` 同时支持 `.xls` 和 `.xlsx`；**表头按列名匹配**（列顺序变化不影响导入），扫描前 10 行定位表头；日期兼容 Excel 日期格式与 `yyyy-M-d`/`yyyy/M/d`/`yyyyMMdd`/中文年月日；同一日期**重复导入即整体覆盖**（先删该日期再插入），幂等。 |
|---|
| | | - **接口**：`POST /api/observation/import`、`GET /api/observation/dates`（按日期汇总站数、中小客流量合计、最近导入时间）、`GET /api/observation/rows?date=&limit=`、`POST /api/observation/delete?date=`。 |
|---|
| | | - **前端**：`traffic-audit-web/src/views/HolidayStat.vue`（专项统计 - 节假日）新增「观测站分日调查数据」卡片：选择文件 → 导入 → 按日期汇总表 → 查看明细（弹窗）→ 删除。 |
|---|
| | | - **实测（真实模板，本机 3305）**：导入 692 行 / 692 站 / 0 跳过 / 0 失败；三项合计与源文件逐项一致（中小客流量 3,523,873、机动车流量 5,487,965、机动车当量 7,140,575）；**692 行 × 25 字段全量逐行比对 0 处不一致**；中文（站名/地市/区县）落库无乱码；重复导入仍为 692 行（覆盖而非累加）；上传非 Excel 返回明确错误。旁证：692 站中小客流量合计 3,523,873 辆 = 352.3873 万辆，与 2026-10-01 节假日「普通国省道」入库值完全一致，印证了数据来源关系。 |
|---|
| | | - **顺带修复**：`pack-deploy.ps1` 把 db 脚本复制进包内 docs 的清单里漏了 `sql_holiday_previous_day_migration.sql`，本次一并补上 `sql_observation_station.sql`；`deploy-templates/README-部署说明.txt` 的 db 清单同步更新。 |
|---|
| | | - **10-03 深夜追加（观测站界面微调）**：①「查看」明细弹窗按模板表头展示原始数据全部字段（观测日期/站号/站名/里程/地市/区县/方向 + 全部车型流量、客货汽车机动车流量、各类当量、速度、拥挤度，另附来源文件名，共 27 列，横向滚动）；②汇总表「中小客流量合计」单位由辆次改为**万辆次**、保留 4 位小数（`formatWanVehicles`，如 3,523,873 → 352.3873）。前端 dev server 已热更新编译通过。 |
|---|
| | | - **10-03 深夜追加（观测站列表/明细修正）**：①**明细行序**原来按 `stationCode` 排序，与 Excel 行序对不上，改为按导入顺序（`id ASC`，即 Excel 行序），便于逐行比对；②明细**列顺序**与模板 26 列完全一致（末尾附来源文件名）；③**观测里程/机动车速度/拥挤度**改为按原始小数显示（`formatPlain`，去尾零，如 50.92 / 43.882 / 0.777 / 58），不再固定 2 位；④**17 个流量与当量列**改为整数显示（`formatInteger`，如 6413），与 Excel 一致；⑤汇总列表「观测日期」改为**正序**（mapper `ORDER BY obs_date ASC`）。已用 10-01/10-02 真实数据验证行序与 Excel 前 5 行一致（中帮/万店/沼山站/邾城站/白云）。 |
|---|
| | | - **状态**：待用户「验收通过」后提交/推送。 |
|---|
| | | |
|---|
| | | --- |
|---|
| | | |
|---|
| | | ### 补充（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）**： |
|---|
| | | 1. 《功能测试报告》《工作日结》改为**本地写、不入库**（`docs/功能测试报告/`、`docs/工作日结/` 已 gitignore，本次 109 个文件移出仓库、本地文件全部保留；其中《模块功能验证状态矩阵_2026-09-02》属团队共享信息，已移到 `docs/` 根目录继续入库）； |
|---|
| | | 2. **入库的是结论**：关键结论/口径/风险/待办写进本文件（`HANDOFF.md`）或 `docs/交接文档_*.md`、`docs/问题汇总/`，与该次代码改动放在同一条提交； |
|---|
| | | 3. 提交粒度与 message：一条提交一个改动（代码+相关文档），前缀 `feat(模块):` / `fix(模块):` / `docs:` / `docs(交接):`；禁止入库临时脚本/调试产物/构建产物/密钥/大体积 sql。 |
|---|
| | | > 参考数据：同事 xyc 55 次提交中 37 次更新本文件、功能测试报告仅 4 次、日结 7 次；此前我方 144 次提交里含 102 份报告 + 106 份日结。 |
|---|
| | | - **打包去密（根因已修）**：旧部署包的 jar 内置 `BOOT-INF/classes/application.yml` 带着**真实密钥与库口令**（外层 application.yml 干净、运行时以外部为准，但 jar 可解压明文可见；且 zip 压缩导致直接 grep 搜不到）。 |
|---|
| | | 现已改为：**进 jar 的配置只有占位符**（`${TRAFFIC_DB_*}`、`${DEEPSEEK_API_KEY:}`、`${TRAFFIC_JWT_SECRET:...}`）；本机真实值走 **Windows 用户环境变量**（`TRAFFIC_DB_PASSWORD` / `DEEPSEEK_API_KEY`），`start-dev.ps1` 增加了从注册表补齐的兜底。 |
|---|
| | | - **新增脚本（已入库）**：`pack-deploy.ps1`（一键打包：构建 → **解压 jar 去密自检，命中真实密钥/明文口令即中止** → 重建前端 → 组装部署包到 `E:\试验\traffic-audit-deploy-<yyyyMMdd>`）、`set-secrets.ps1`（轮换后交互式更新本机环境变量）、`deploy-templates/`（打包模板入库：外部 application.yml、启动脚本、nginx 示例、db 建表 sql、部署 README——原先只在未跟踪的旧包里，删包即丢）。 |
|---|
| | | - **清理旧部署件（用户确认后执行）**：删除 `E:\试验\traffic-audit-deploy-20260913`（目录 + **69.9 MB 的 zip**）、`deploy\traffic-audit-deploy-20260913`、`_deploytest`、空 `out`/`deploy`；旧 `target` jar 由 `mvn clean` 覆盖。全盘复查（仓库 + `E:\试验`）：**已无任何含明文 key 的 jar / 压缩包 / 文本文件**。 |
|---|
| | | - **干净新包已产出**：`E:\试验\traffic-audit-deploy-20260927`（336 文件 / 96 MB，前端含最新「按市州汇总」；jar 内置配置全占位符）。 |
|---|
| | | - **运行状态（09-27 实测）**：dev 后端 `8090`、前端 `8080` 在运行；**本机数据库为 MySQL80 `localhost:3308/traffic_audit`（root/口令走环境变量）**——注意 `docs/交接文档_2026-09-23.md` 写的 `3305` 是**同事机器**的配置，本机没有 3305，别再照抄。 |
|---|
| | | - **待办（接手优先）**： |
|---|
| | | 1. **【需用户】轮换已泄露的 DeepSeek key**（控制台新建 + 删旧 → 跑 `set-secrets.ps1`）； |
|---|
| | | 2. **【需用户】服务器换包**：删旧包/zip → 拷 `traffic-audit-deploy-20260927` → 改 `backend\application.yml` 数据库三处（需要 AI 分析再填 `deepseek.api-key`）→ `start-backend.cmd`； |
|---|
| | | 3. P0 三项不变：P0-2 亿元投资项目按 Q7 按月追列、P0-3 导出前基数体检 +《数据缺失清单》页、P0-4 缺 2026-06/09 母版； |
|---|
| | | 3.1 **汇总大表现状复核（2026-09-27 实测，母版 `docs/生成汇总大表/2026年8月道路运输量汇总表.xlsx` + 最近生成件）**： |
|---|
| | | - **累计列公式没覆盖到当期（实测 306 格）未落实**，确切位置（母版 `docs/生成汇总大表/2026年8月道路运输量汇总表.xlsx`）： |
|---|
| | | · `公交!U5:U76`、`出租!U5:U76`、`网约车!U5:U76` 各 72 格 = 216 格，公式 `=V5+X5+Z5+AB5+AD5+AF5`（只累加 2025 年 1~6 月；U 列表头为空，位置在"2025年1月"块左侧，对应 2026 块的 `S` 列"2026年累计"，语义即"2025 年累计"）； |
|---|
| | | · `城市客运!U4:U39` 36 格（同模式，只 6 个月）；`班线包车!DU4:DU57` 54 格（`DU2` 表头直接写"1-3月累计"，只 3 个月——属版式未随月份扩展）。 |
|---|
| | | → 业务口径为"可清空留空"；**生成件与母版逐格相同**（证实程序只补当期列、不碰历史列）。09-22 差异报告按另一分页口径统计为"304 格（含中口径明细 88 格）"，本次按公式模式定位到的是上述 306 格，两者为同一类问题、分页归类不同。 |
|---|
| | | - **2026-09-27 已处置：母版里的"人工核算草稿累计列"整体清空**（用户确认"这一列都可以留空，是人工核算时弄的草稿"）。清空范围共 **577 格**：`公交/出租/网约车!U5:U76`、`城市客运!U4:U39`、`班线包车!DU4:DU57`（含表头 `DU2`"1-3月累计"）、`中口径明细!U99:U188`、`中口径客运量!AB5:AB188`。 |
|---|
| | | · 依据：这些列在整本工作簿里**没有任何公式引用**（全簿扫描 0 命中），且程序**不写它们**（生成件与母版逐格相同）→ **只改母版即可，无需改代码**。 |
|---|
| | | · 做法：直接改 xlsx 内部 XML（只去对应单元格的 `<f>/<v>`、保留样式），**避免 openpyxl 保存导致全簿公式缓存值丢失**（该坑已实测复现：用 openpyxl 存一次后 `公交!S5` 由 98460.97 变 None，会破坏"中口径排名用母版 2025 静态列"）。 |
|---|
| | | · 验证：重新生成 2026-08（母版变更使缓存自动失效，`staleCache=true`）→ 新旧生成件逐格比对：**仅这 577 格变为空，19 页签与尺寸不变，其它一律不动**；依赖母版缓存值的口径（中口径排名 M3、道路运输周转量 G4、货运量排名 B4、城市汇总 B3、公交 S5/Q5、中口径明细 C99、班线包车 Q4）**全部一致**。 |
|---|
| | | · 备份（本地保留、不入库）：`docs/生成汇总大表/_bak_202608母版清空草稿累计列前_20260927.xlsx`；新生成件已存 `D:\桌面\生成数据\生成_道路运输量汇总表_2026-08 (4).xlsx`。 |
|---|
| | | · **表头措辞修复（按人工定稿为准）**：`轨道、轮渡!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 手工"规上货运量(万吨）"）与市州名（程序按设计用短名"武汉/恩施/林区"、手工用"武汉市"等全名）——需业务确认以哪版为准。 |
|---|
| | | |
|---|
| | | · ⚠ **待同事确认**：手工定稿侧也把这些草稿列留空，否则比对会从"程序有值/手工有值"变成"程序空/手工有值"（同类差异、方向相反）。 |
|---|
| | | |
|---|
| | | · **清空的 7 列对照表（供同事复核；引用数为清空前的全簿扫描）**： |
|---|
| | | |
|---|
| | | | 页签 | 列 / 范围 | 清空格数 | 原表头 | 公式语义 | 清空前缓存值（首行样例） | 同页引用 | 跨页引用 | |
|---|
| | | | --- | --- | ---: | --- | --- | --- | ---: | ---: | |
|---|
| | | | 公交 | `U`（U5:U76） | 72 | （无表头） | `=V5+X5+Z5+AB5+AD5+AF5` → 2025 年 1~6 月累计 | 88908.91 | 0 | 0 | |
|---|
| | | | 出租 | `U`（U5:U76） | 72 | （无表头） | `=V5+X5+Z5+AB5+AD5+AF5` → 2025 年 1~6 月累计 | 39797.94 | 0 | 0 | |
|---|
| | | | 网约车 | `U`（U5:U76） | 72 | （无表头） | `=V5+X5+Z5+AB5+AD5+AF5` → 2025 年 1~6 月累计 | 16384.07 | 0 | 0 | |
|---|
| | | | 城市客运 | `U`（U4:U39） | 36 | （无表头） | `=V4+X4+Z4+AB4+AD4+AF4` → 2025 年 1~6 月累计 | 206639.67 | 0 | 0 | |
|---|
| | | | 班线包车 | `DU`（DU4:DU57） | 54 | 1-3月累计 | `=DO4+DQ4+DS4` → 1~3 月累计 | 5566.8922 | 0 | 0 | |
|---|
| | | | 中口径明细 | `U`（U99:U188） | 90 | （无表头） | `=V99+X99+Z99+AB99+AD99+AF99+AH99` → 2025 年 1~7 月累计 | 1102278.385724 | 0 | 0 | |
|---|
| | | | 中口径客运量 | `AB`（AB5:AB188） | 184 | （无表头） | `=AC5+AE5` → 2024 年 1~2 月累计 | 6088.1871 | 0 | 0 | |
|---|
| | | |
|---|
| | | · **⚠ 同名列别清错（反例对照）**：`中口径明细!AB3 = "2025年4月"` 是**正常月份列**，被 **700+ 处同页 + 34 处跨页公式引用**（例如 `中口径明细!J5 = I5/AB5-1` 2026 年 4 月同比、`T5 = S5/SUM(V5,X5,Z5,AB5,…)-1` 累计同比、`AT5 = X5+V5+Z5+AB5+…` 2025 累计、`中口径客运量!I11 = 中口径明细!AB11`），**本次未动、也不能清**。判据：该列**有表头**、**被引用数远大于 0**、公式语义是"被别的格引用"而不是引用其它月份列。 |
|---|
| | | |
|---|
| | | - **生成件里错误值 356 个 `#DIV/0!` + 13 个 `#REF!`**：班线包车 228+8、中口径明细 64+2、货运 38+3、中口径客运量 26；业务口径未定（是否清成空白）。 |
|---|
| | | - **城市客运页表头仍是日期序列号（确证未修）**：母版与生成件第 2 行第 3 个月起均为序列号（G2=46082、I2=46113…），1、2 月是文字；`fixCityMonthHeaderText()` 未覆盖该页 → "按表头文字匹配列"方案在该页失效。（此前文档标"待核实"，现已确证。） |
|---|
| | | - 缺 2026-09 母版（目录仅 7 月/8 月/版式原型 + 2 个 `_bak_*`）→ 9 月出表会 `ready=false`，需拍板方案 A（程序扩列）/ B（Excel 小工具）。 |
|---|
| | | 4. 汇总大表 304 格「2025 累计列少加 7、8 月」清空（业务已确认口径，待执行）； |
|---|
| | | 5. 本机历史临时目录待清（`outputs/` 41MB、`_shots/`、`_test_check*`、`_test_passenger`、`.tmp_*`、`_tmp_codexhome`）；`_给同事_2026-09-21/`（52MB 全库备份）属交付件，未动。 |
|---|
| | | |
|---|
| | | ## 最新（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` 最新 `db0ee92`（含投资明细取数/导入修复）；合并后 `mvn -q -DskipTests compile` 通过。 |
|---|
| | |
|---|
| | | - **今日已完成（远端提交）**：数据查看补齐网约车/个体客运、按市州汇总与导出 Excel、汇总大表进度弹窗与结果落盘缓存。 |
|---|
| | | - **汇总大表差异复核（2026-09-22）**：软件输出与手工定稿经 Excel 全量重算后逐格比对，930 条差异中实质数值差异 314 条；其中 304 条为 2025 累计列少加 7、8 月（业务已确认可清空），10 条 ` 货运` 历史同比业务已确认软件正确。报告见 `docs/问题汇总/汇总大表_软件输出与手工定稿差异清单_2026-08_20260922.md`，明细见同名目录 CSV。 |
|---|
| | | - **未完成重点不变**：P0-2《亿元投资项目》按 Q7 追列、P0-3 导出前基数体检、P0-4 2026-09 母版；其余见 `docs/交接文档_2026-09-21.md` 第 4 章。 |
|---|
| | | - **关机交接快照（2026-09-22 17:20）**： |
|---|
| | | - **git**：`main` 已同步 `origin/main`；本快照提交后会再次推送，当前无未提交业务代码。 |
|---|
| | | - **运行状态**：dev 后端 `8090`、前端 `8080` 均未运行，也未发现对应 Java/Node 进程；`backend.log` 最后写入 09-21 17:29，`frontend.log` 最后写入 09-21 17:36。MySQL80(`3305`)、MySQL57(`3306`) 仍为 Running，关机后随系统停止，按惯例无需手工处理。 |
|---|
| | | - **下次启动**：在项目根目录执行 `powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1`；数据库数据均已持久化，无需重建。 |
|---|
| | | - **保留产物**：汇总大表 930 条差异报告/CSV、投资 156→129 格比对报告、`_tmp*_0922.*` 和 `_tmp/gen_new_0922/` 等测试产物均保留，未经确认不删除。 |
|---|
| | | - **下次优先**：P0-2《亿元投资项目》按 Q7 追列、P0-3 导出前基数体检、P0-4 2026-09 母版；投资遗留还需处理武汉物流/黄冈客运 8 月源数据、潜江 6/7 月历史错值重导和未覆盖清单落文件。 |
|---|
| | | |
|---|
| | | ### 补充（2026-09-22 下午，投资取数修复第一轮） |
|---|
| | | |
|---|
| | |
|---|
| | | - **待核实**：`docs/交接文档_2026-09-21.md` 的 P2-2「城市客运页表头仍是日期序列号」可能过时——代码已有 `fixCityMonthHeaderText()`（09-03 加入）， |
|---|
| | | 建议跑一次 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） |
|---|
| | | |
|---|
| | |
|---|
| | | - **2026-08-28 复核「点数据导入浏览器崩溃」（打包测试环境，部分用户）**：重点排查 `GET /api/import/batches`——后端 limit 上限 200；全表 81 条、error_detail 最长 2.6KB、全量响应约 17KB（前端只取 50 条）；前端表格仅 8 列短字段（errorDetail 不渲染）、无轮询/定时器。**结论：接口不是崩溃根因**（若接口有问题，所有用户都会崩，而非"部分用户"）。现象符合客户端环境差异（第三方扩展注入/旧显卡驱动/低配内存，与 08-27 迅雷扩展+Intel 旧驱动结论一致）。建议对崩溃用户依次验证：无痕模式→换 Edge→禁扩展，并看 chrome://crashes。 |
|---|
| | | - 【新需求·仅记录未实现·2026-08-28】增加**经济指标试算功能**：领导非常关注经济指标，**货运是大头**；常驻现场的所有人都要会计算货运相关数据（货运量/周转量等）。领导经常要求把某个数据「压一压」，今后考虑在软件里增加试算功能——可按需要调整/测算指标数值（如模拟下调某企业/某口径的货运量后看汇总与趋势影响），辅助现场人员快速试算与应对。 |
|---|
| | | |
|---|
| | | - 【待办·2026-10-03】**数值精度统一改造**：把既有业务表的数值列由 `double` 改为 `DECIMAL(30,15)`，Java 实体字段由 `Double/Float` 改为 `BigDecimal`，与节假日表、观测站表统一口径（用户 2026-10-03 明确要求，择机实施）。 |
|---|
| | | - 现状盘点（traffic_audit，2026-10-03 查询）：**16 张表、共 228 个 double 列**——`freight_turnover_import` 48、`city_bus_monthly` 34、`h2032_enterprise_monthly` 33、`city_taxi_monthly` 29、`wyc_order_monthly` 22、`h2031_enterprise_monthly` 18、`h204_vehicle_quarterly` 12、`scale_split_transport` 9、`investment_monthly` 5、`investment_system` 5、`wyc_total_monthly` 4、`h204_auth_vehicle` 2、`investment_project` 2、`passenger_individual_monthly` 2、`transport_auth_vehicle` 2、`vehicle_track_mileage` 1。 |
|---|
| | | - 已是 decimal 口径、无需改动：`holiday_calendar` / `holiday_passenger_coefficient` / `holiday_passenger_flow` / `holiday_vehicle_flow` / `observation_station_flow`。 |
|---|
| | | - 改造范围不只是改列类型：实体类字段类型、导入解析（不要经 double 中转）、计算与取整逻辑、报表导出格式化，以及存量数据的迁移脚本，都要一起改；改完要做逐表数值抽查。 |
|---|
| | | |
|---|
| | | ## 八、每日交接约定 |
|---|
| | | 1. 新对话第一步：读 `AGENTS.md` + `HANDOFF.md`；涉及 AI 分析/审核时参考 `docs/` 与数据库表结构。 |
|---|
| | | 2. 每天结束时：更新 `HANDOFF.md`（进展、坑、新需求、待办），再关对话。 |
|---|
