工程量清单的 Git Diff：在浏览器本地对比两版清单 Excel，让每一版清单变化都有迹可循。
A local-first Excel BOQ diff tool for construction cost engineers and quantity surveyors.
Important
v0.1.0 是首个公开版本。在线演示由 main 分支通过 GitHub Pages 部署。清单文件仅在当前浏览器内存中处理，不会上传到服务器。
招标清单经过补遗、澄清或修订后，造价人员常用 VLOOKUP、XLOOKUP、条件格式和逐行核对来找变化。只要中间插入或删除一行，按行号比较就可能整体错位；重复编码、缺失编码、编码变化和列顺序差异也会让单一键值匹配失效。
BOQ Diff 面向投标报价、最高投标限价、送审结算和审定结算等复核场景，先独立映射两版字段，再用确定且可解释的规则匹配清单项，最后导出可追溯的 Excel 差异报告。详细业务流程见行业工作流。
- 本地读取两份
.xlsx或.csv，选择工作表并独立映射字段 - 自动识别标题行和常见字段名称，预览参与比较的数据
- 识别空白、章节、合计和说明行，保留排除原因及来源行号
- 匹配唯一编码、重复编码、无编码项目和编码变化项目
- 为模糊候选显示分数、理由和最多三个候选，支持人工确认与撤销
- 比较编码、名称、项目特征、单位、工程量、综合单价和合价
- 统计新增、删除、修改、未变化、待确认及已确认净金额影响
- 按状态、变化字段和关键字筛选，通过详情面板逐字段复核
- 导出带冻结、筛选、配色和数字格式的 Excel 复核报告
- 内置完全虚构且可重复生成的演示数据
- 打开在线演示或本地应用，分别导入基准版与对比版；也可以点击“加载演示数据”。
- 选择工作表，检查两侧字段映射和数据预览，然后开始比较并处理待确认项。
- 查看汇总与字段级差异，按需筛选，最后导出 Excel 复核报告。
默认单文件上限为 25 MB，单工作表有效数据行上限为 30,000 行。超限文件会给出说明，不会静默截断。
- 文件解析、匹配、差异计算和报告生成均在浏览器本地完成
- 工作簿内容、清单行、文件名历史、项目金额和导出结果不会写入持久存储
- 刷新页面或点击“清空数据”后，当前会话中的文件数据会被释放
localStorage仅可保存主题、非敏感字段映射偏好和比较容差- 应用不包含后端、账号、遥测、广告、外部 API 或文件上传接口
- 站内演示数据等静态资源请求不包含用户导入的文件内容
完整设计约束和威胁边界见隐私与安全。处理敏感项目资料前，仍应遵守所属组织的信息安全制度。
匹配是本地、确定且可解释的，相同输入和参数会得到相同结果。工程量和价格是需要比较的变化字段，不作为主要身份依据。
| 阶段 | 规则 | 结果 |
|---|---|---|
| 1 | 两侧非空编码规范值一致，且各自唯一 | 自动匹配 |
| 2 | 重复编码内按名称、项目特征和单位消歧 | 明确候选自动匹配，歧义项待确认 |
| 3 | 名称、项目特征和单位规范值完全一致 | 自动匹配，并突出编码变化 |
| 4 | 经单位、关键词和规格数字缩小候选后计算加权相似度 | 高可信自动匹配，中间分数或近似候选待确认 |
默认高可信阈值为 0.88，0.72 至 0.88 进入待确认；存在分数非常接近的候选时不会擅自匹配。所有规则、权重、排除项、金额计算和限制见匹配规则。
| 格式 | v0.1.0 | 说明 |
|---|---|---|
.xlsx |
支持导入与报告导出 | 公式仅使用文件中可安全取得的缓存结果，不在浏览器中重新计算 |
.csv |
支持导入 | 作为一个工作表处理 |
.xls |
不支持 | 请先用 Excel 或 WPS 另存为 .xlsx |
| GBQ、GTJ 等商业软件专有文件 | 不支持 | 本项目不解析专有工程文件 |
| PDF、扫描件 | 不支持 | v0.1.0 不含 OCR |
两份表可以使用不同的标题行、字段名称和列顺序。读取编码时优先保留显示文本，以尽量保留前导零。
需要 Node.js 24 LTS 和 npm。依赖版本以 package-lock.json 为准。
git clone https://github.com/KanadeK/boq-diff.git
cd boq-diff
npm ci
npm run dev| 命令 | 用途 |
|---|---|
npm run dev |
启动开发服务器 |
npm run build |
类型检查并生成 dist |
npm run preview |
本地预览生产构建 |
npm run lint |
运行代码检查 |
npm run format |
使用 Prettier 格式化项目文件 |
npm run format:check |
检查格式 |
npm run typecheck |
运行 TypeScript 检查 |
npm run test |
运行默认单元测试 |
npm run test:unit |
运行单元测试 |
npm run test:e2e |
运行 Playwright 端到端测试 |
npm run verify |
依次运行发布前必要检查和构建 |
npm run generate:fixtures |
重新生成确定性的虚构测试工作簿 |
Vite 的 base 配置为 /boq-diff/。推送 main 后，Pages 工作流会用 npm ci 安装锁定依赖，运行校验与构建，上传 dist，再通过 GitHub 官方 Pages Actions 部署。仓库所有者仍需在 Settings > Pages > Build and deployment > Source 中选择 GitHub Actions。
发布前检查清单、截图生成、CI Badge 校验和手动发布步骤见发布指南。工作流已准备部署，但本地项目不会自行创建仓库、推送、发布 Pages 或创建 Release。
v0.1.0 只比较两个清单工作表，不提供 AI、账号、后端、数据库、OCR、PDF 或商业软件专有文件解析，也不做定额套用、自动组价、市场询价、多人协作、自动漏项判断或计价合规判定。应用不会直接修改用户上传的原始文件。
本工具只用于机械性差异识别和复核辅助。匹配、金额影响与导出报告不能替代注册造价工程师或项目造价人员的专业判断，使用者应回到原始文件和合同资料核验结论。
项目的术语与业务背景参考《建设工程工程量清单计价标准》GB/T 50500-2024，但不复制或内置标准全文，也不表示任何官方认证、授权或自动合规能力。
- v0.1：单工作表对比、字段映射、精确与模糊匹配、Excel 差异报告
- v0.2：多工作表批量配对、字段映射模板、单位工程批量导出
- v0.3：机械性质量检查 CostLint 与可配置规则包
- v0.4：跨项目综合单价横向对比和本地历史基准库
- v0.5：可选 Tauri 桌面版与超大工作簿优化
后续能力不会提前塞入 v0.1.0。完整范围见路线图。
内置演示数据和 tests/fixtures 中的工作簿均为完全虚构，由脚本确定性生成，不对应任何真实项目、公司、商业软件模板或受版权保护的计价数据库。请勿在 Issue 或测试夹具中提交真实项目资料。
欢迎提交 Bug、功能建议和脱敏后的清单模板兼容性问题。开始前请阅读贡献指南和行为准则；安全漏洞请按安全政策私下报告。
Copyright (c) 2026 KanadeK. 本项目采用 MIT License。