pcc-bulk-materials

Download, reconstruct and consolidate Taiwan PCC bulk material price PDFs

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0
Author: pseudoich85

Documentation

PCC 大宗資材價格 n8n 節點

將工程會六類材料的價格趨勢 PDF 下載、封存、還原表格並彙整為歷史 CSV。以 TypeScript 開發,安裝包包含編譯完成的 JavaScript;n8n 執行時不需要 Python、系統 PDF 工具、原生套件編譯或修改容器設定。

目標:n8n 2.39.10。建置使用該版本的 n8n-workflow 2.39.3 型別;獨立核心與開發工具需要 Node.js 24 以上。

從 npm 安裝

在自架 n8n 的 Settings → Community Nodes → Install 輸入固定版本名稱:

n8n-nodes-pcc-bulk-materials@0.1.0

安裝後搜尋 PCC Bulk Materials。此為未經 n8n 官方驗證的 community node,需由 Owner/Admin 安裝,並已允許安裝未驗證社群節點。完整步驟見 安裝與回復說明。

套件包含三個工作流程 JSON、設定範本及編譯完成的節點。可先執行 npm pack n8n-nodes-pcc-bulk-materials@0.1.0,解開下載的 tgz,取得 package/workflows/ 與 package/config/。

本機交付內容

以下大型資料、原始碼壓縮檔及驗證報告屬本機交付,不包含在公開 npm 套件中;npm 套件只包含節點、工作流程、設定及文件。

  • artifacts/n8n-nodes-pcc-bulk-materials-0.1.0.tgz:供手動安裝的編譯套件。
  • artifacts/pcc-bulk-materials-source-0.1.0.zip:原始碼、測試、鎖定相依版本與工作流程。
  • artifacts/pcc-reference-seed.zip:915 份固定版本 PDF 及原始人工補值,供離線重建歷史。
  • artifacts/material_price_history.csv:JavaScript 產生並通過 Python 比對的歷史 CSV。
  • workflows/:手動初始化、週一 08:00 更新、手動重建三個可匯入工作流程,預設均未啟用。
  • 三個工作流程已套用您確認的四份砂石空表雜湊例外;略過時記錄警告,其他空表或內容變更仍阻擋發布。從節點選單新增的空白節點仍維持嚴格預設。
  • artifacts/parity-report.json、artifacts/container-smoke.json、artifacts/verification.md:資料及容器驗證結果。
  • artifacts/SHA256SUMS.txt:交付檔案 SHA-256。

安裝與啟用

請依 安裝與回復說明 操作。可從 npm 透過 Community Nodes 安裝,也保留 .tgz 手動安裝方式。無需重建 image、變更 Compose、開放 Code node 外部模組或配置 Python runner。

沿用已具備的 /files/dist/ 掛載、持久保存與 n8n 存取授權。若部署使用 queue workers,所有會執行工作流程的實例必須能存取同一份套件與資料;本交付不自動改動該部署。

三個操作

操作 行為
Sync 向工程會取得目錄,每次最多下載/解析 25 份 PDF;完整處理完畢才發布 CSV。
Rebuild 從本機 PDF 與人工補值重新彙整,不連工程會。解析版本與內容未變時使用磁碟快取。
Parse PDF 讀取 binary data,依原始檔名辨識材料與民國期別;每個價格明細輸出一個 item,附診斷資訊與正確輸入連結。

Sync/Rebuild 每次節點呼叫只執行一次,不會依輸入 item 數重複執行。摘要的 hasMore=true 表示仍有批次;隨附工作流程會循環處理。成功、無新資料、失敗與中間批次皆記錄執行歷程。單檔錯誤會保留其他成功進度並停止循環;預設 n8n 節點會拋出錯誤以標示執行失敗。

儲存根目錄預設 /files/dist/pcc-bulk-materials/,節點只接受 /files/dist/ 下的絕對路徑,並遵守 n8n 的既有檔案存取限制。Dry Run 只檢查目錄及待處理數量,不下載 PDF、不建立資料夾,也不寫入日誌或鎖檔。檔案與欄位詳見 資料規則。

相容性

相容基準固定為 原專案 commit e7b6588574697c094e5aaa7f640d341279166a41。PDF 來自行政院公共工程委員會,請標示資料來源。

本版忠實保留原 Python 的排序、分組、最後有效價格、區間極值及第一個來源檔名規則,也保留部分歷史 PDF 的重疊字元與異常數值。這些是明確選定的相容行為,未將它們當作資料修正。詳見 已知差異與限制。

這是未經 n8n 官方驗證的 community node。包含 PDF 解析依賴與本機檔案操作,不宣稱符合官方 verified community node 條件。公開 npm 套件沿用現有 UNLICENSED 授權標示,未額外授予開源授權。

開發與驗證

npm ci --ignore-scripts
npm test
npm run reference:download
python -m pip install -r requirements-baseline.txt
npm run reference:python
npm run reference:compare
npm run pack:release
npm run smoke:install

完整資料驗證會下載約 111 MiB 的公開 PDF;參考檔案放在 .reference/,不混入正式套件。smoke:install 需要本機 Docker,建立獨立、結束後自動移除的官方 n8n 測試容器;不連接正式 n8n 資料。開發環境若限制本機網路,HTTPS 測試需要允許連線到 localhost。

pdfjs-dist 的 worker、CMaps 與標準字型皆由套件相依項目提供,不從 CDN 載入。純表格抽取不呼叫 canvas;省略可選 canvas 套件時,PDF.js 可能印出渲染能力警告,這不影響已驗證的文字/線條解析。

Discussion