# 交通货运统计审核系统 —— 交接文档（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:50 续接实测）

### 1.1 git

| 项 | 值 |
| --- | --- |
| 分支 | `main` |
| 本轮起点 HEAD | `8b739ce docs(交接): 统一 09-22 关机快照（合并同事版本，修正运行状态为实测：8090/8080 在运行）` |
| 远端 | 本轮开始前已同步公司 `origin/main`；本次续接新增的文档提交见 `git log` |
| 远端地址 | `origin` → `http://61.183.254.94:3000/r/trafficAudit.git`（分支 `main`）——**只用公司 gitea 单仓库**，个人 gitee 已弃用 |

### 1.2 服务与进程

| 项 | 值 |
| --- | --- |
| dev 后端 8090 | **运行中**（09-23 08:48 启动，日志出现 `Started TrafficAuditApplication`） |
| dev 前端 8080 | **运行中**（09-23 08:48 启动，日志出现 `App running at`） |
| 数据库 | MySQL，库 `traffic_audit`，配置 `jdbc:mysql://localhost:3305/traffic_audit`，`root/root`；本机 `MySQL57`、`MySQL80` 服务均 **Running** |
| 其它 node 进程 | 存在若干 `node`/`cmd`（08:42 起），为 Codex 自身组件，**勿动** |

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

### 1.3 启动 / 停止

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

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

### 1.4 git 工作流（硬规矩）

```powershell
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% 已解决。

### 2.1 09-23 续接：潜江投资物流月报重导（本次新增）

- 按遗留重导潜江物流 2026-06、2026-07；核对当前应用配置时发现实际连接库是 `localhost:3305`，而 09-22 功能测试报告记录的验证库是 `localhost:3308`。
- 当前 `3305` 库中，潜江 2026-08 仍挂旧项目“潜江传化公路港项目”并保留 `5173/12000/5173/1440`，说明上一轮 08 月修正未落到本次运行库；`3308` 当前无法连接。
- 本次只上传潜江单文件重导 6/7/8 三个月，均为 `success=1`；三个月均改为“中国虾谷冷链仓储物流园” `11947.9 / 0 / 1135 / 0`。
- 重复重导幂等（每月 1 条、1 个项目、无重名主档），2026-08 物流明细导出第 180 行端到端核对通过。
- 报告：`docs/功能测试报告/功能测试报告_潜江投资物流月报重导_2026-09-23.md`。

---

## 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 已废弃）提供**读指定范围**接口：

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

请求头：

```http
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 / 2026-08** ✅ 已于 2026-09-23 在当前应用库 `3305` 用对应月份源表重导并完成幂等/导出验证；后续不要再沿用 09-22 报告的 `3308` 验证结论。
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. 关键文件与命令索引

| 用途 | 路径 / 命令 |
| --- | --- |
| 每日总入口 | `HANDOFF.md`（本仓库根） |
| 项目规约 | `AGENTS.md`（仓库根） |
| 系统总交接 + P0/P1/P2 | `docs/交接文档_2026-09-21.md` |
| 汇总大表专项交接 | `docs/问题汇总/汇总大表问题交接_2026-09-21.md` |
| 汇总大表差异清单/明细 | `docs/问题汇总/汇总大表_软件输出与手工定稿差异清单_2026-08_20260922.md` + 同名 CSV |
| 投资比对/修复报告 | `docs/功能测试报告/数据比对报告_投资明细表软件生成与人工版_2026-09-22.md`、`docs/功能测试报告/功能测试报告_投资明细表取数修复_2026-09-22.md` |
| 潜江重导验证报告 | `docs/功能测试报告/功能测试报告_潜江投资物流月报重导_2026-09-23.md` |
| 历史问题坑索引 | `docs/问题汇总/问题与注意事项汇总_2026-09-16.md` |
| 汇总大表母版 | `docs/生成汇总大表/`（`{yyyy}年{M}月道路运输量汇总表.xlsx`） |
| 投资模板/输入/输出 | `docs/投资/模板/`、`docs/投资/输入/…`、`docs/投资/输出/` |
| 启停 | `start-dev.ps1` / `stop-dev.ps1`（沙箱外） |
| 后端/前端日志 | `backend.log`、`traffic-audit-web/frontend.log` |

---

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