BOQ Diff 的匹配规则遵循四个原则：
- 确定性：输入、映射和参数相同时，结果相同。
- 可解释：每个配对都记录匹配类型、分数和理由。
- 保守性：歧义候选进入待确认，不为了提高匹配率而强行配对。
- 身份与变化分离：名称、项目特征、单位和编码用于识别项目；工程量与价格主要用于比较变化。
一条基准项最多匹配一条对比项，反之亦然。已在前一阶段确定的配对不会在后一阶段被重复使用。
界面和报告保留原始显示值，匹配使用派生的规范值。文本规范化至少包含：
- Unicode NFKC；
- 全角空格转换为普通空格；
- 去除首尾空格，合并连续空白；
- 英文字母转为小写；
- 常见中文标点使用统一形式；
m²、㎡、m2等单位形成可比较值；- 保留可能改变含义的数字、规格和型号。
项目编码按文本处理，优先读取 Excel 单元格的显示文本，以尽量保留 001234 之类的前导零。规范化不会把编码强制转换成数字。
数值解析支持 Excel 数字、千分位逗号、前后空格、全角空格、人民币符号、负号和括号负数。公式单元格只在文件中存在可安全读取的缓存结果时使用该结果；应用不重新计算公式，也不伪造缺失值。
以下行默认不作为清单项目参与匹配：
- 完全空白行；
- 明显章节标题行；
- 合计、小计或总计行；
- 只有名称，但没有编码、单位、工程量和价格的说明行。
排除行必须保留来源文件、工作表、原始行号和排除原因，并导出到“未参与行”。分类规则应偏保守；无法明确判断时，允许使用者回到字段预览核对。
同时满足以下条件时直接配对：
- 两边项目编码均非空；
- 规范化编码完全一致；
- 该编码在基准版和对比版中各出现一次。
匹配理由记录为“项目编码唯一且一致”。
当同一规范化编码在任一侧出现多次时，不按行号或出现顺序直接配对。算法在相同编码组内比较：
- 项目名称；
- 项目特征；
- 单位。
单位一致和项目特征相似的组合优先。配对使用固定排序与确定性选择策略；同分时按稳定的来源顺序打破计算顺序，但不会仅因行号接近而提高身份相似度。理由记录为“重复编码消歧”并附相似度。
如果多个组合非常接近，项目进入待确认。
对仍未配对的项目，当项目名称、项目特征和单位的规范值完全一致时，可视为明确匹配。这一阶段覆盖缺失编码以及编码发生变化的情况。
若两侧非空编码不同，差异中必须突出“项目编码变化”，不能因为项目已经配对而隐藏编码差异。
只处理前三阶段后仍未匹配的清单项目。为避免对所有剩余行进行全量两两比较，先利用单位、关键词、规格数字或倒排索引缩小候选集。每条基准项最多进入约 50 个候选的相似度计算。
默认加权信号为：
| 信号 | 权重 |
|---|---|
| 项目名称 | 30% |
| 项目特征 | 45% |
| 单位 | 20% |
| 编码局部信息 | 5% |
字符串相似度算法必须可测试且不调用 AI。默认判定区间为：
- 分数大于或等于 0.88：在没有近似并列候选时可自动匹配；
- 分数大于或等于 0.72 且小于 0.88：进入待确认；
- 分数低于 0.72：不自动配对，剩余两侧分别成为删除和新增候选。
若第一候选和第二候选分数非常接近，即使第一候选达到高可信阈值，也进入待确认。实现使用的阈值、候选限制和歧义判定参数应随报告导出，便于复核和版本追踪。
每条待确认基准项最多展示三个候选，并逐项显示编码、名称、项目特征、单位、匹配分数和理由。复核人员可以：
- 确认某个候选为匹配项；
- 判定基准项已删除；
- 跳过，继续保留待确认；
- 撤销本次人工决定。
人工确认会改变最终配对和金额统计，因此导出报告必须标明是否经过人工确认。未处理的待确认项不计入“已确认净金额影响”。
匹配后比较以下字段：
- 项目编码；
- 项目名称；
- 项目特征；
- 单位；
- 工程量；
- 综合单价；
- 合价。
默认数值容差为：
| 字段 | 容差 |
|---|---|
| 工程量 | 0.000001 |
| 综合单价 | 0.01 元 |
| 合价 | 0.01 元 |
差值绝对值不超过容差时，该数值字段视为未变化。容差可以在高级设置中修改，并应写入“比较参数”。文本差异使用规范值判断，但详情与报告展示原始值。
每个变化字段显示基准值、对比值、绝对变化和百分比变化。百分比通常为 (对比值 - 基准值) / 基准值。当基准值为零或必要数值缺失时，不生成 Infinity、NaN 或误导性百分比，而显示“基准为 0”或“无法计算”。
有效合价按以下顺序确定：
- 源文件合价可以安全解析时，使用原合价，来源标记为
original。 - 原合价为空，但工程量和综合单价都有效时，使用二者乘积，来源标记为
calculated。 - 缺少必要数值时，不生成合价，来源标记为
missing。
计算合价不能伪装成源文件原值。公式无安全缓存结果时同样不能伪造数值。
| 状态 | 金额影响 |
|---|---|
| 已匹配项目 | 对比版有效合价减基准版有效合价 |
| 新增项目 | 对比版有效合价 |
| 删除项目 | 0 减基准版有效合价 |
| 待确认项目 | 不计入已确认净影响，单独汇总待确认金额 |
任一侧缺少计算所需的有效合价时，该项目金额影响显示“无法计算”，不能按零处理。最终净影响只汇总已经确定且金额可计算的项目。
结果状态包括 added、removed、changed、unchanged 和 pending。匹配结果同时保留：
- 基准版和对比版来源行；
- 匹配阶段或类型；
- 置信度；
- 人类可读的匹配理由；
- 人工确认状态；
- 字段变化；
- 金额影响和合价来源。
- 相似度衡量文本接近程度，不理解合同、工法或计价规则。
- 规范化不能解决所有编码体系和单位语义差异。
- 标题、合计和章节识别依赖可测试的机械规则，特殊模板仍可能需要人工映射和核对。
- 公式不会在浏览器内重新计算，缺少缓存结果时可能无法得到金额。
- 结果不能判断漏项、组价合理性、市场价格或标准合规性。
改变权重、阈值、规范化或金额规则属于用户可观察行为，应更新测试、本文档和变更日志。