zhizhijie
8 天以前 ecf2b3c4ca25709aff8aae6f5969f0595d55206f
docs/½»½ÓÎĵµ_2026-09-23.md
New file
@@ -0,0 +1,197 @@
# äº¤é€šè´§è¿ç»Ÿè®¡å®¡æ ¸ç³»ç»Ÿ â€”— äº¤æŽ¥æ–‡æ¡£ï¼ˆ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` ä¸ºå‡†ã€‚*