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 模式）
- 下載這個專案（綠色 Code 按鈕 → Download ZIP），解壓縮。
- 雙擊
index.html。一開始會載入 12 筆示範資料（全部是假的），可以先輸入 3 或 透天 試試看。
- 準備你自己的資料：打開
data/listings.example.csv（可用 Excel 開），照欄位填好，
用「另存新檔 → CSV UTF-8（逗號分隔）」存檔。
- 回到網頁，展開最下面的「資料來源」→「選擇 CSV 檔」。
選一次之後，這台電腦的瀏覽器會記住，下次打開不用再選。
- 物件有更新時，重新存 CSV、再選一次檔就好。
欄位可以自己加減，只要有「售版編號」這一欄就行（名稱可以在 config.js 改）。
設定（config.js）
用記事本打開 config.js：
| 設定 | 說明 |
|---|
title | 網頁標題 |
idField | 編號欄位的名稱，要和 CSV 第一列一模一樣 |
showFields | 查到後要顯示哪些欄位、順序；[] 代表全部 |
searchFields | 關鍵字要在哪些欄位找；[] 代表全部 |
highlight | 某些值標顏色，例如「已成交」標灰色 |
source.type | 'csv'、'csvUrl' 或 'api' |
CSV 網址模式（Google 試算表）
- Google 試算表 →「檔案」→「共用」→「發布到網路」→ 選工作表、格式選「逗號分隔值 (.csv)」→ 發布，複製網址。
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 自動化、房仲遠端助理
- 👤 作者：留白事務所
