交通货运统计审核系统 —— 交接文档（2026-09-23）

用途：新对话/接手人先读 HANDOFF.md + 项目根 AGENTS.md，再读本文，即可无缝接力。
与其它文档的关系：本文只写 09-23 的增量（现状快照 + 本次对话新增的腾讯文档读取调研 + 当前待办入口）；
系统结构、P0/P1/P2 全量遗留仍以 docs/交接文档_2026-09-21.md 为准，不重复。

0. 先读这一页（接手第 1 小时）

1. 先把系统跑起来（见 §1.3），再谈改代码。脚本必须在**沙箱外**运行。
2. 本次对话新增结论：腾讯文档在线表格「能不能读、怎么读、trafficAudit 能不能自己读、官方 API 行不行」全部调研完，见 §3。
3. P0 三件事不变：①《亿元投资项目》按 Q7 追列；② 导出前「基数体检 + 弹窗 +《数据缺失清单》页」只做了一半；③ 缺 2026-06 / 2026-09 母版。详见 docs/交接文档_2026-09-21.md §4。
4. 硬规矩不变：改完必须写《功能测试报告》→ 更新《工作日结》→ 推送公司 gitea（origin，§1.4）。不要强推、不要覆盖同事代码。

1. 现状快照（2026-09-23 08:44 实测）

1.1 git

1.2 服务与进程

判断服务是否起来：**只看日志**（后端 Started TrafficAuditApplication + Tomcat started on port(s): 8090；前端 App running at）。
沙箱内 Get-NetTCPConnection 会静默失败/报无匹配，据此判断会误判。

1.3 启动 / 停止

# 项目根目录，必须在沙箱外（提权）运行
powershell -NoProfile -ExecutionPolicy Bypass -File start-dev.ps1
# 停止：
powershell -NoProfile -ExecutionPolicy Bypass -File stop-dev.ps1

脚本会自动跳过已在监听的端口；关机后服务自然停止，无需手工处理。

1.4 git 工作流（硬规矩）

git fetch origin
# 先合并远端 main（有必要就解冲突，禁止强推）
git add -- <改动文件>
git commit -m "docs: ..."
git push origin main

2. 09-22 已完成（承上，已在远端）

• 投资明细表「软件生成 vs 人工版」逐格比对（2026-08）：156 格差异，定位到 3 类「会静默出数」的取数问题（导出按项目名匹配/库内无当月数沿用上期值、库内同名双档取到旧档、导入丢数）。报告 docs/功能测试报告/数据比对报告_投资明细表软件生成与人工版_2026-09-22.md。
• 投资取数修复第一轮：导出 3 处 + 导入 2 处（含新发现的「潜江导入 2018 年历史 sheet」），回归后逐格差异 156 → 129，无新增差异，未覆盖行能自动告警。报告 docs/功能测试报告/功能测试报告_投资明细表取数修复_2026-09-22.md。
• 汇总大表软件输出 vs 手工定稿复核（2026-08）：Excel 全量重算后逐格比对，930 条差异中实质数值差异 314 条；恰 304 条为「2025 累计列少加 7、8 月」（业务已确认该列可清空），10 条 货运 历史同比业务已确认软件正确。报告 docs/问题汇总/汇总大表_软件输出与手工定稿差异清单_2026-08_20260922.md，明细 CSV 同目录。
• 数据查看页：补齐网约车总数/网约车订单/个体客运三类查看入口，新增「按市州汇总 + 导出 Excel」，口径上移筛选、空列隐藏、表头补单位。
• 汇总大表导出缓存：导出结果落盘缓存（docs/生成汇总大表/_cache/，gitignore）+ 数据指纹守卫（依赖源表 CHECKSUM TABLE + 母版文件身份，换母版必失效），失效时弹窗给说明。
• Codex 输入卡顿修复复核通过：09-22 重启后 Codex++ 守卫脚本仍启用，主渲染进程空闲 CPU 约 13.3%（单核），较修复前约 115% 已解决。

3. 腾讯文档在线表格读取调研（本次对话新增）

3.1 背景

用户给定在线表格（只读分享链接）：

https://docs.qq.com/sheet/DQ2ZLR09Kcm9ZcUpI?nlc=1&tab=000004

文档名 《2026年十一数据》，权限**只能查看**，共 10 个页签：铁路、民航、道路、水路、高速公路、普通国省道、营业性客运量、人员流动量汇总、报厅办1、报厅办2。

3.2 实测结论一：分享链接的内容**可以读**（显示值层面）

做法（Codex 内置浏览器 + CUA/Playwright，无需任何腾讯账号/API）：

1. 打开文档 → 触发「打印」→ 选择「**整个工作簿**」→ 进入**打印预览**；
2. 预览把每个页签渲染成 SVG 打印页段（本次实测共 15 段）；
3. 读取 SVG 中 <text> 节点即可得到**当前显示值**：表头、日期、数值、百分比，连 #DIV/0! 这种错误文本也能拿到。

能力边界（很重要）：

• ✅ 能读：当前**显示值**（含打印范围内的表头/日期/数值/百分比/错误文本）。
• ❌ 不能读：原始**公式**（拿到的是结果不是 =…）。
• ❌ 不能读：**隐藏行列**（打印预览不含隐藏内容）。
• ❌ 不能读：**打印范围外**的内容。
• ❌ 不易恢复：精确 A1 单元格坐标（按显示布局切分，不保证与单元格一一对应）。

3.3 实测结论二：**trafficAudit 目前读不了在线文档**

代码调研（全仓无腾讯文档/分享链接/腾讯 Open API 任何集成）：

• 前端只支持**本地文件上传**：el-upload，接受 .xlsx/.xls/.et（网约车报告另有 .docx）——traffic-audit-web/src/views/DataImport.vue:57、DataImport.vue:502；
• 后端接口收 MultipartFile——DataImportController.java:33；
• 服务层用 Apache POI WorkbookFactory.create(file.getInputStream())——DataImportService.java:192；
• 「目录导入」只扫描**服务器本地目录**，不访问外网。

结论：要靠软件自己读在线表格，**必须新增集成**（下述官方 API 是唯一正规路径）；否则只能像本次一样借助浏览器「打印预览」人工/脚本抓显示值。

3.4 实测结论三：**腾讯文档官方 API 可以按单元格读取**（无需大模型/OCR）

官方 Open API（V3，V2 已废弃）提供**读指定范围**接口：

GET https://docs.qq.com/openapi/spreadsheet/v3/files/{fileId}/{sheetId}/{range}
# 例：/files/ABCDE123abcde/BB08J2/A10:D11

请求头：

Access-Token: {ACCESS_TOKEN}
Open-Id: {OPEN_ID}
Client-Id: {CLIENT_ID}
Accept: application/json

要点：

• range 用 A1 表示法，返回 gridData.rows[].values[].cellValue；
• 权限需 scope.sheet 或 scope.sheet.readonly；
• 必须走**腾讯文档 OAuth 2.0 用户授权**拿到 Access-Token/Open-Id；
• 单次限制：行 ≤ 1000、列 ≤ 200、总单元格 ≤ 10000；
• 仅凭公开分享链接、没有应用凭证/OAuth，不能匿名调用；
• 官方文档：https://docs.qq.com/open/document/app/openapi/v3/sheet/get/get_range.html

3.5 建议（若后续要落地）

• 只读少数**已知范围**的数值 → 直接走**官方 Open API V3**（按 A1 范围读，稳定、可写进代码）。
• 浏览器「打印预览」只作**临时/一次性**取证手段，不要写进产品逻辑。
• 真正开发前需先准备：腾讯文档**开放平台应用**（Client-Id）+ OAuth 回调 + 用户授权，并确认目标文档所在账号能授权该应用。

4. 当前待办

4.1 投资明细表（下一轮）

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》或页面提示。

4.2 汇总大表

• 304 格「2025 累计列少加 7、8 月」：业务已确认该列**可清空**，等落实现（清空/修正规则以业务最终意见为准）。

4.3 既有 P0/P1/P2（不变，见 docs/交接文档_2026-09-21.md §4）

• P0-2《亿元投资项目》按 Q7 追列（ReportExportService.java:6251 仍写同一格）；
• P0-3 导出前基数体检（getLastMidIssues() 无调用方）；
• P0-4 2026-06/09 母版缺失；
• P2-2「城市客运页表头仍是日期序列号」可能过时（代码 09-03 已加 fixCityMonthHeaderText()），待跑一次 2026-08 导出核对后再改；
• 其余 P1/P2 见 09-21 总交接文档。

5. 关键文件与命令索引

本文由 2026-09-23 会话生成，用于新对话续接。系统全景仍以 docs/交接文档_2026-09-21.md 为准。