# 功能测试报告 — 投资月报「匹配 + 校验 + 变更清单」引擎（Step1 写入前一步）
- 日期：2026-09-17
- 被测对象：`docs\投资\工具\匹配与校验.py`（新增，**只读**）
- 目的：在真正写文件之前，把 Step1 的三个判断全部算清楚并落证据：
① 哪些项目能按名称匹配上（→ 更新 6 列）；② 哪些要新增；③ 哪些数据对不上（→ 弹窗提示）
---
## 一、功能说明
| 能力 | 实现 |
| --- | --- |
| 读目标明细表 | 客运 `输出\X月客运站投资明细表.xlsx` 的 `明细` 表；物流 `输出\X月物流站场投资明细.xls` 的 ` 分项目投资完成情况` 表。自动跳过合计/分类行，只留项目行 |
| 读投资系统查询结果 | `输入\模板_查询结果(投资系统-客运+物流 YYYY.M).xls`；按文件名或「时期」列识别年月，自动区分**本期**（权威对照）与**上月**（校验基数） |
| 名称匹配 | ① **精确匹配**：统一全角/半角括号、去空白后相等 → 更新
② **疑似同一项目**：再去掉括号字符与结尾「项目」二字后相等，或相似度 ≥0.90 → **不自动合并、不重复新增**，列入人工确认
③ **相似 0.80–0.90**：仍按新增，但给出「请确认是否同一项目」提示 |
| 三方数值比对 | 市州月报 ⇄ 投资系统（本期）：`自开始建设累计 / 自年初累计 / 本月完成`，容差 0.05 |
| 月度校验 | `本月自年初累计 = 上月自年初累计 + 本月完成`（上月值取**上月**那份投资系统文件的 G 列，按用户口径 a） |
| 输出 | `变更清单_.tsv`（动作/目标行号/6 列新值）+ `匹配校验报告_.md` |
---
## 二、测试环境
Python 3.14 + `_pylibs`（xlrd/openpyxl）；数据：2026 年 7 月；全程只读，不写任何目标表。
---
## 三、用例与结果
| 编号 | 用例 | 预期 | 实际 | 结论 |
| --- | --- | --- | --- | --- |
| M01 | 读两张目标明细表并识别项目行 | 只识别项目行，排除合计/分类行 | 客运 **49** 行、物流 **99** 行 | ✅ 通过 |
| M02 | 与市州月报解析结果（151 行）按名称匹配 | 精确匹配 + 待定 + 新增 三类互斥且总数守恒 | 客运 45+0+3=48 ✓（另目标表独有 4）；物流 94+3+6=103 ✓（另目标表独有 5） | ✅ 通过 |
| M03 | 名称写法不同不得重复新增 | 宽松等价/≥0.90 相似 → 归入「疑似同一项目」 | 物流 3 个命中：`鄂湘赣商贸物流中心一期`⇄`(一期)`、`荆门北站顺洋物流基地`⇄`…基地项目`、`荆门智慧冷链物流园`⇄`…园项目`；均**未**进入新增 | ✅ 通过 |
| M04 | 相似但差异较大的不得自动合并，要提示 | 0.80–0.90 给出人工确认提示 | 客运 `郑万高铁南漳综合客运枢纽` ⇄ `郑万高铁巴东综合客运枢纽` 0.83（实为**不同项目**：南漳属襄阳、巴东属恩施）→ 按新增处理并提示；物流 `崇阳县综合物流园及配套设施建设项目` ⇄ `崇阳县国家级综合物流枢纽…` 0.82 → 提示 | ✅ 通过 |
| M05 | 三方数值比对（市州月报 ⇄ 投资系统本期） | 逐项目比对三个字段 | 客运 **0 处**不一致；物流 **2 处**：`九州通沃田国际供应链中心项目` 自年初累计 8000 vs 4200（差 −3800，**真实差异，需业务确认**）、`神农架物流园` 自开始建设累计 7535.45 vs 7535.5（差 0.05，舍入） | ✅ 通过 |
| M06 | 投资系统里查不到的项目不得计为差错 | 单列一节，不计入差异 | 客运 9 个、物流 15 个（如 黄石新港国胜智慧公路港、武汉万吨·华中冷链港…），单独列出 | ✅ 通过 |
| M07 | 月度校验：缺上月文件时的行为 | 按用户口径 (a) 提示「需每月放一份」，**不阻断**、不误报 | 本期只有 2026.7 的查询结果 → 报告写明「月度校验：跳过（未找到上月投资系统数据表）」 | ✅ 通过 |
| M08 | 变更清单可直接驱动写入侧 | 每条含 品类/动作/目标行号/项目名称/6 列新值 | `变更清单_2026-07.tsv` 共 **148** 条（更新 139 + 新增 9），列名与目标表列一一对应 | ✅ 通过 |
| M09 | 只读性 | 源文件与目标表均不被修改 | 目标表/源文件哈希未变 | ✅ 通过 |
---
## 四、本轮发现（需要业务确认，已在报告中逐条给出证据）
| # | 现象 | 判定 |
| --- | --- | --- |
| 1 | `九州通沃田国际供应链中心项目` 自年初累计：市州月报 8000 / 投资系统 4200 | **真实数值不一致**，差 3800 → 按需求「存在数据不一致的弹窗提示」处理 |
| 2 | 3 处名称写法不同（物流） | 疑似同一项目 → 程序**不合并、不重复新增**，弹窗提示人工确认 |
| 3 | 客运 `郑万高铁南漳` / `郑万高铁巴东` 相似度 0.83 | 实为**两个不同项目**，说明匹配阈值不能一味调低 |
| 4 | 9 个将新增的项目（客运 3 + 物流 6） | 含黄石隐藏行项目 `阳新县焦山物流仓储中心`（证明隐藏行必须取） |
| 5 | 缺「上月投资系统数据表」 | 按用户口径 (a)：每月需再放一份**上月**的查询结果；缺失时校验跳过并提示 |
---
## 五、结论
- M01–M09 **全部通过**；Step1 的三个判断（更新 / 新增 / 数值不一致）已全部算出并留证据。
- 下一步「写入侧」所需的一切输入已就绪：`变更清单_2026-07.tsv` + 校验报告 + `_bak_` 备份策略 + 输出目录 `输出\2026年7月\`。
- 写入侧将用 **Excel COM**（本机 Python 无 win32com；且 .xls 目标表要保持公式与格式，不能用 openpyxl/xlwt 另存）。
- 本轮仍**只读**：未改任何源文件、未写入任何目标表、未改业务程序代码。