tw-listing-lookup｜售版編號查詢

房仲門市常見的狀況：同事拿著 DM 或售版上的編號問「這間是哪裡？誰的案子？」。 這個小網頁讓大家輸入編號就馬上看到地址、承辦人、價格、狀態；也可以用關鍵字找（例如「透天 業務A」）。

• 免安裝：一個資料夾，雙擊 index.html 就能用。
• 資料自己管：資料放在你自己的 CSV、Google 試算表或自己的 API，不經過任何第三方。
• 手機也好用：可以把網址做成書籤或 QR code，index.html?id=12 會直接查 12 號。
• 不只房仲：任何「編號 → 資料」的查詢都適用，例如庫存編號、會員編號、器材編號。

線上試用：https://larryveryhandsome.github.io/tw-listing-lookup/

---

適合誰

你是	建議用法
門市只有一台電腦、物件表在 Excel	CSV 模式（預設）：Excel 另存 CSV，網頁上選檔一次就記住
物件表在 Google 試算表、想讓手機也能查	CSV 網址模式：試算表發布成 CSV，把網址填進 config.js
已經有自己的後台系統	API 模式：把 API 網址填進 config.js

---

5 分鐘開始（CSV 模式）

1. 下載這個專案（綠色 Code 按鈕 → Download ZIP），解壓縮。
2. 雙擊 index.html。一開始會載入 12 筆示範資料（全部是假的），可以先輸入 3 或 透天 試試看。
3. 準備你自己的資料：打開 data/listings.example.csv（可用 Excel 開），照欄位填好， 用「另存新檔 → CSV UTF-8（逗號分隔）」存檔。
4. 回到網頁，展開最下面的「資料來源」→「選擇 CSV 檔」。 選一次之後，這台電腦的瀏覽器會記住，下次打開不用再選。
5. 物件有更新時，重新存 CSV、再選一次檔就好。

欄位可以自己加減，只要有「售版編號」這一欄就行（名稱可以在 config.js 改）。

---

設定（config.js）

用記事本打開 config.js：

設定	說明
title	網頁標題
idField	編號欄位的名稱，要和 CSV 第一列一模一樣
showFields	查到後要顯示哪些欄位、順序；[] 代表全部
searchFields	關鍵字要在哪些欄位找；[] 代表全部
highlight	某些值標顏色，例如「已成交」標灰色
source.type	'csv'、'csvUrl' 或 'api'

CSV 網址模式（Google 試算表）

1. Google 試算表 →「檔案」→「共用」→「發布到網路」→ 選工作表、格式選「逗號分隔值 (.csv)」→ 發布，複製網址。
2. config.js 改成：

source: {
  type: 'csvUrl',
  csvUrl: '貼上剛剛的網址',
},

⚠️ 個資警告：「發布到網路」代表任何知道網址的人都能下載整份 CSV（網址可能被轉傳、被搜尋到）。 showFields 只決定畫面上顯示哪些欄位，擋不住下載。

可以發布的欄位	絕對不要發布的欄位
售版編號、案名、地址（到路段）、類型、總價、承辦人、承辦人電話、狀態	屋主／客戶姓名與電話、身分證、底價、委託價、備註裡的私事

做法：在試算表另開一個只有公開欄位的分頁（例如用 =ARRAY_CONSTRAIN 或 QUERY 從主表抓），只發布那個分頁；主表不要發布。 如果載入的 CSV 欄位名稱含「屋主、客戶、姓名、身分證、電話（非承辦人）」這類字眼，網頁頂端會跳出紅色警告。 另外：放在 GitHub Pages 上的網頁本身也是公開的，知道網址的人都能逐號查詢；要限制對象請改用內網或有登入的 API。

API 模式

source: {
  type: 'api',
  api: {
    url: 'https://你的網域/api/listing?id={id}',   // {id} 會換成輸入的編號
    fields: { 地址: 'address', 承辦人: 'agent.name' }, // 顯示名稱: API 欄位（可用 a.b）
    listPath: '',                                    // 回傳是 { result: [...] } 時填 'result'
  },
},

• API 回傳可以是物件、陣列，或 { data: [...] }；空物件、空陣列或 HTTP 404 都會顯示「找不到」。
• API 要允許瀏覽器跨網域讀取（CORS），並建議加上登入或內網限制，不要讓外人能逐號查詢。

---

需要哪些金鑰？

原則上不需要，所以沒有附 docs/金鑰申請.md。

• CSV 模式：完全不需要任何帳號或金鑰。
• CSV 網址模式：Google 試算表「發布到網路」產生的 CSV 網址不需要 API 金鑰（也不需要開 Google Cloud 或試算表 API）；步驟見上方「CSV 網址模式」。
• API 模式：本工具不會幫你送出任何金鑰或登入資訊。如果你自己的 API 需要金鑰，請改用內網／同網域的轉接端點，不要把金鑰寫進 config.js（放上 GitHub Pages 後，任何人都看得到）。

給開發者

index.html          畫面
css/style.css       樣式（含深色模式）
config.js           設定
data/sample.js      網頁內建的示範資料（和範本 CSV 內容相同，測試會檢查）
data/listings.example.csv  CSV 範本
js/lookup.js        查詢核心：CSV 解析、編號正規化、關鍵字搜尋、API 回應轉換（純函式）
js/app.js           畫面邏輯
tests/              單元測試（node:test，不用裝任何套件）

npm test

輸入的編號會先正規化：全形轉半形、去空白、去開頭的 0，所以「０１２」「 12」「012」都會查到 12 號。 所有顯示的資料都會做 HTML 跳脫，不會因為資料裡有 <script> 而被注入。

注意事項

• 原則上查詢結果以你提供的資料為準，本工具不保證資料正確。
• 放入個人資料時，請自行遵守《個人資料保護法》，並控管誰能打開這個網頁。

已知問題

• 只用模擬資料測過 CSV 網址／API 模式，沒有接真實 Google 試算表或真實 API。
• 匯入的資料會留在這台瀏覽器；放入個人資料時要自行遵守《個人資料保護法》並控管誰能開這個網頁。
• 只實測 Chromium（桌機與 375 寬）。

完整的發布前檢查（八道閘門）見 RELEASE_CHECK.md。

授權

Apache License 2.0

---

🛠️ 需要客製化？

這個工具是開源的，可以免費使用。如果你想要：

• 改成符合你們公司的流程、欄位或品牌
• 串接你現在在用的系統（LINE、Google 表單、POS、會計軟體……）
• 幫你安裝、架站、教學，或長期維護

歡迎加 LINE 跟我們聊。我們會依需求的範圍與複雜度報價，原則上以實際報價單為準。

• 💬 LINE：林其衞（請註明「售版編號查詢 客製化」）
• 🏢 留白事務所：網頁設計、AI 自動化、房仲遠端助理
• 👤 作者：留白事務所