# 功能测试报告_投资月报格式探测与字段映射表_2026-09-17

## 一、功能说明

| 项 | 内容 |
| --- | --- |
| 需求来源 | 《投资月报数据处理与多表更新需求说明（最终汇总版）》第九节确认事项 D（格式探测）、E（字段映射表先出草案，不改程序）；用户 2026-09-17 答复「你先弄一份映射表出来看看，先不改程序」 |
| 本次交付 | ① `docs\投资\工具\格式探测.py`（可复跑的只读探测脚本）② `docs\投资\输出\市州月报格式差异报告_2026-07.md` ③ `docs\投资\输出\字段映射表_草案_2026-07.xlsx`（7 个 sheet）④ `docs\投资\输出\格式探测_2026-07.md / .tsv`（脚本输出） |
| 功能边界 | **只读**：不修改任何源文件、目标表；不写入数据库；不改动业务程序代码 |
| 探测范围 | `docs\投资\输入\客运（客运站）\7月` 10 个文件、`docs\投资\输入\物流（物流园区）\7月` 17 个文件、`docs\投资\模板` 6 张目标表、`docs\投资\输入\模板_查询结果(投资系统-客运+物流 2026.7).xls` 1 个投资系统项目表 |

## 二、测试环境

- 操作系统：Windows；工作目录 `D:\文档\ChatGPT\traffic-audit`
- 运行时：Python 3.14（`xlrd 2.0.2` 位于项目 `_pylibs`，`openpyxl 3.1.5`）
- 源文件格式分布：`.xls`（24 个）、`.xlsx`（5 个）、`.et`（1 个，WPS）

## 三、测试用例

| 编号 | 用例（输入） | 预期 | 实际 | 结论 |
| --- | --- | --- | --- | --- |
| TC01 | `格式探测.py --month 2026-07` 全量扫描 27 个源文件 | 27 个文件全部给出：数据工作表、表头行、数据起止行、项目行数、字段列位 | 27/27 输出完整，无异常报错 | ✅ 通过 |
| TC02 | 多工作表工作簿（林区 27 张表、潜江 27 张表、襄阳 .et 7 张分月表） | 选中**本期**（2026-07）数据表 | 林区选中 `2026.7`（表头日期 2026.07.24）、潜江选中 `潜江传化2022.3`（表头日期 2026.07.22）、襄阳选中 `2026年7月` | ✅ 通过 |
| TC03 | 无序号列布局（随州物流，名称在 A 列、B 列为空列） | 能识别 2 个项目行，名称列 = A | 数据 5~6、项目行 2、名称列 A | ✅ 通过 |
| TC04 | 缺序号行（十堰客运 4 行中 2 行无序号；黄石物流 8 行中 1 行无序号） | 无序号行也要算作项目行 | 十堰客运 12~15 / 4 行；黄石物流 9~18 / 8 行 | ✅ 通过 |
| TC05 | 列位右移（襄阳客运 .et 多「建设规模」列） | 识别为 建设性质=E…自开始建设累计=I、自年初累计=K | 输出 `建设性质=E 总投资=H 自开始建设累计=I 本年计划投资=J 自年初累计=K 本月完成=L 建设阶段=M 形象进度=N` | ✅ 通过 |
| TC06 | 数据区混排的「市州汇总行 / 分类行 / 小计行 / 合计行 / 签字栏」不得被当成项目行 | 不计入项目行 | 孝感/黄石/随州/十堰等表的市州行、`一、二、三、`分类行、`小计`、`统计负责人：`「投资完成率」签字行均被排除；十堰物流仅统计出 38 行（含武汉历史区块）并在报告中标记 | ✅ 通过 |
| TC07 | 空模板工作表不得被选中（随州首个表「月2」、林区/潜江的 `Sheet2/Sheet3`） | 选中真正含数据的工作表 | 随州选中 `Sheet2`；林区/潜江按表头日期选表 | ✅ 通过 |
| TC08 | 目标表与投资系统项目表的列位采集 | 6 张目标表 + 1 个系统表字段列正确 | 客运明细表 B/H/J/K/L/M、物流明细表 B/H/J/K/L/M、汇总表 D/I/W/X、十五五 B/G/H/I/J、亿元 C/F…W、经济强县 B/E/G/H/I/J、系统表 B=单位 G=自年初累计 | ✅ 通过 |
| TC09 | 生成的 `字段映射表_草案_2026-07.xlsx` 可正常打开 | 7 个 sheet、内容完整 | openpyxl 复读通过：`1.说明与口径 / 2.源文件标准列位 / 3.逐市州列位映射 / 4.明细表到目标表映射 / 5.投资系统项目表 / 6.差异与待确认清单 / 7.输出命名与格式建议` | ✅ 通过 |
| TC10 | 报告结论与人工核对一致 | 差异清单可复现 | 对 7 个重点文件（十堰物流、潜江/林区、襄阳客运、恩施/黄石物流、随州物流、武汉南山汉口）逐个打开源文件人工复核，报告描述与源文件一致 | ✅ 通过 |
| TC11 | 重复运行幂等（脚本只读） | 源文件哈希不变 | 重新运行后源文件未变化（脚本仅 open 读取） | ✅ 通过 |

## 四、发现的问题与处置（本轮开发过程中）

| # | 问题 | 根因 | 处置 |
| --- | --- | --- | --- |
| 1 | 部分文件字段标签全为空 | 早期探针脚本用闭包 `lambda` 延迟绑定工作表对象，循环结束后指向了最后一张空表 | 改为默认参数绑定 `lambda r, c, _s=sh: ...` |
| 2 | 大量 `.xls` 报 `IndexError: tuple index out of range` | `pick_sheet` 里误写 `score > best[2]`（`best` 只有 2 个元素） | 改为 `best[1]` |
| 3 | 首次运行全部 `.xls` 打开失败 | 探测脚本未把项目自带 `_pylibs`（xlrd）加入 `sys.path` | 脚本自动向上查找并注入 `_pylibs` |
| 4 | 随州物流、林区物流项目行数识别为 0 | 项目行判定只认「A 列是序号 + B 列有名称」，遇到「无序号列」「缺序号」即漏判 | 判定规则改为：名称列非空 + 非小计/合计/分类行 + 数值锚点存在；随州（名称在 A）、林区（A 空）均可识别 |
| 5 | 多工作表工作簿取到历史月数据 | 只按字段命中数打分，未考虑月份 | 增加「表头区年月标记」（文本日期 + Excel 日期序列号）优先加分 |

## 五、结论

- 格式探测与字段映射表两项交付**已完成并通过测试**（TC01–TC11 全部通过）。
- 探测结论：27 个源文件中 20 个与目标明细表列位完全一致，解析风险集中在 4 类（多市州混排、工作表名与实际月份不符、列位右移 1 列、建设阶段/形象进度未分列），已在报告第四节按高/中/低分级并给出处置建议。
- 仍未闭环（需业务确认，见映射表 Sheet6）：汇总表与亿元投资项目的更新列与需求文档列出的指标对不上；恩施/黄石物流「建设阶段/形象进度」合并列口径；1 月上年基数取哪一列；客运缺 7 个市州文件的处理方式。
- 本轮未改动任何业务程序代码（符合用户「先不改程序」的要求）。