上传清单，三分钟完成交付前体检。
Privacy-first Excel quality checker for Bills of Quantities.
文件仅在当前浏览器的本机内存中处理，不上传清单，不接入后端、数据库、统计分析或遥测。 打开在线页面时，浏览器仍需从当前站点下载应用自身的静态资源；用户选择的 Excel 内容不会因此发送到站点。
git clone https://github.com/KanadeK/boq-check.git
cd boq-check
npm ci
npm run dev
BoQ Check 是面向造价工程师、招标代理、咨询单位和项目成本人员的工程量清单 Excel 交付前体检器。它检查清单的结构、数据完整性、文本一致性和行金额逻辑，帮助编制人员在交付前发现可追溯的问题。
当前版本只读取 .xlsx，不直接修改或覆盖源文件。每条问题记录均尽量关联工作表、原 Excel 行号、字段和清单编码，并可导出 XLSX 问题台账或 JSON 报告，供编制人员回到原计价软件或源表中复核修正。
检查结果仅用于辅助复核，不构成造价审核结论。
- 导出模板不统一：从前 30 行推测表头，并允许人工确认字段映射。
- 交付前人工排查耗时：集中检查空值、数字格式、文本清洁、重复与金额逻辑。
- 问题难以回溯：保留工作表、Excel 行号、字段、编码及关联冲突行。
- 敏感清单不适合上传：解析、检查和报告生成均在浏览器本地完成。
- 团队口径不一致：以具备唯一编号、说明、等级和建议的规则输出问题台账。
- 不同业务需要不同规则：规则引擎与界面、Excel 解析和导出逻辑解耦，便于社区扩展。
计价软件或 Excel 导出清单 → 编制人导入 .xlsx → 选择工作表并确认字段映射 → 执行规则检查 → 查看问题与原表位置 → 导出问题台账 → 回到原计价软件修正 → 重新导出并复查。
BoQ Check 位于“交付前自检”环节，不替代编制、复核、审核或审批职责。
以下截图由仓库内的真实应用与完全虚构的演示清单生成。演示项目名为“示例工程——综合楼清单质量检查演示”，不对应任何真实工程、单位或造价。
| 导入与隐私提示 | 工作表与字段映射 |
|---|---|
|
 |
访问：https://kanadek.github.io/boq-check/
可以直接加载内置的虚构演示清单，也可以选择自己的 .xlsx。v0.1.0 的文件大小上限为 30 MB；旧版 .xls 请先在可信的本地软件中另存为 .xlsx。刷新或关闭页面会清除当前会话中的文件与检查结果。
| 编号 | 规则 | 默认等级 | 说明 |
|---|---|---|---|
| BQ001 | 项目名称缺失 | 错误 | 仅检查识别为清单明细的行 |
| BQ002 | 计量单位缺失 | 错误 | 排除标题、小计、说明和空白行 |
| BQ003 | 项目编码缺失 | 警告 | 不假定所有清单类型都强制具有编码 |
| BQ004 | 项目特征缺失或过短 | 警告 | 可关闭；提示人工补充或确认 |
| BQ005 | 数值格式错误 | 错误 | 支持千位分隔、全角负号和括号负数 |
| BQ006 | 非正常负值 | 错误 | 检查工程量、综合单价和合价 |
| BQ007 | 零值提醒 | 警告 | 可关闭；零值并不自动等同于错误 |
| BQ008 | 行金额计算不一致 | 错误 | 使用十进制定点语义和可调容差比较 |
| BQ009 | 同编码核心信息冲突 | 错误 | 只在同一工作表内比较，并输出冲突行 |
| BQ010 | 疑似完全重复清单 | 警告 | 只提示，不自动删除 |
| BQ011 | 同名称和特征的单位不一致 | 警告 | 基于规范化文本在同表内比较 |
| BQ012 | 单位写法不统一 | 提示 | 识别 m2、㎡、m² 等同义写法 |
| BQ013 | 文本清洁问题 | 提示 | 检查多余空格、换行和不可见控制字符 |
| BQ014 | 疑似占位描述 | 警告 | “暂估”等内容只提示人工确认 |
| BQ015 | 无法取得公式结果 | 警告 | 不承担 Excel 公式重算 |
| BQ016 | 相同清单描述价格差异提醒 | 提示 | 至少 3 条有效记录；不是市场价格判断 |
规则的准确触发条件、归一化方式和测试要求见 docs/rules.md。
需要 Node.js 22 或更高版本、npm 10 或更高版本。
git clone https://github.com/KanadeK/boq-check.git
cd boq-check
npm ci
npm run devVite 会在终端显示本地地址。打开页面后可以选择：
- 点击“加载演示清单”，使用仓库提供的完全虚构数据走完整流程；
- 点击“选择文件”，导入不超过 30 MB 的
.xlsx； - 选择工作表，确认表头行与字段映射；
- 开始检查，在结果页筛选、搜索并打开问题详情；
- 导出 XLSX 问题台账或 JSON 机器可读报告。
npm ci
npm run lint
npm run format:check
npm run typecheck
npm run test
npm run build
npx playwright install
npm run test:e2e常用命令：
| 命令 | 用途 |
|---|---|
npm run dev |
启动本地开发服务器 |
npm run generate:demo |
重新生成虚构演示 XLSX 与预期快照 |
npm run test |
运行单元测试和组件测试 |
npm run test:e2e |
运行 Playwright 端到端测试 |
npm run screenshots |
用真实应用流程更新文档截图 |
npm run build |
类型构建并生成 dist/ |
架构和数据流见 docs/architecture.md。生产构建按 /boq-check/ 基础路径发布到项目的 GitHub Pages 地址。
- Excel 字节仅在当前浏览器会话中读取和处理，不上传到服务器。
- 不把文件内容写入
localStorage、IndexedDB、Cookie 或远程存储。 - 不包含后端、数据库、登录、AI、第三方分析、广告或遥测。
- Excel 解析与规则执行放在 Web Worker 中；取消检查会终止对应任务。
- 报告由浏览器本地生成并通过下载保存，不覆盖源文件。
- 刷新或关闭页面后，应用不保留当前文件和检查结果。
- 页面自身的静态资源请求、托管平台访问日志、浏览器扩展和操作系统行为不属于“Excel 内容上传”，也不由本项目控制。
完整威胁边界、自托管建议和验证方法见 docs/privacy.md。
v0.1.0 适合对常见工程量清单 .xlsx 做交付前结构和质量提示，主要支持最新版 Chrome、Edge 和 Firefox。它不提供：
.xls解析；- 工程量重算；
- 定额套用；
- 材料价格审核或市场价格合理性判断；
- Excel 公式重算；
- 自动修改、删除或生成所谓“修复版清单”；
- 对国家、行业、地区或合同规则的正式合规审查；
- “清单完全正确”或“通过审核”的结论。
自动表头识别、行分类和字段映射可能受复杂合并单元格、特殊模板或公式缓存缺失影响，开始检查前应由用户确认映射，检查后仍需专业人员结合合同、图纸、计价依据和项目背景复核。
为避免恶意或异常压缩包耗尽浏览器资源，v0.1.0 最多处理 100 个工作表、全簿 100,000 个非空行和 1,000,000 个非空单元格；XLSX 压缩包最多 4,096 个条目、单条实际解压 64 MiB、实际总解压 128 MiB，并拒绝分卷、ZIP64 和加密压缩包。以上是安全拒绝阈值，不是性能承诺；接近阈值的正常文件也建议拆分后检查。
本项目参考工程量清单常见字段和交付前复核流程。住房城乡建设部公告中的标准名称为《建设工程工程量清单计价标准》，编号为 GB/T 50500-2024；可查阅住房城乡建设部官方公告。
BoQ Check 未宣称、也不代表获得 GB/T 50500-2024 认证，不自动判断清单是否完全符合该标准。仓库不复制标准正文；规则只描述本工具公开实现的质量检查逻辑。使用者应通过合法渠道查阅现行标准、合同与适用的地区规定，并由具备相应职责的专业人员作出判断。
以下方向不在 v0.1.0 实现范围，尚无交付时间承诺：
- 两版清单差异对比；
- 用户自定义规则导入导出；
- 地区规则包；
- 批量文件检查；
- 更多计价软件导出模板适配；
- CLI 版本。
路线图不会把云端上传、自动造价审核或形式上的“标准认证”作为当前功能承诺。优先级与验收门槛见 docs/roadmap.md。
请先阅读 CONTRIBUTING.md，再使用“规则建议”Issue 模板描述业务动机、适用字段、触发与不触发样例、误报边界、默认等级和处理建议。示例必须完全虚构，不得上传真实清单、客户信息或受版权保护的标准正文。
每条新规则应具备稳定的唯一 ID，并至少覆盖一个正常用例和一个异常用例；涉及跨行比较时，还应验证同工作表作用域和不同工作表隔离。提交 Pull Request 前运行全部质量检查。
MIT License。第三方依赖分别遵循其自身许可证。
English overview: BoQ Check is a browser-only .xlsx preflight checker for Bills of Quantities. It helps identify structural, completeness, text-consistency, and row-amount issues with traceable worksheet and row references. Workbook data stays in the current browser session. Results are review aids, not quantity recalculation, pricing advice, standards certification, or a formal cost-audit conclusion.