2026-10-30 排程更新：公司訂單改為每天 Asia/Taipei 05:00，自動查詢所有已註冊會員前一天 00:00（含）至當天 00:00（不含）的訂單。每位會員只傳一個日期區間，不再查詢最新十筆或最近十日，也不每十五分鐘重查。歷史資料不刪除。會員端已移除同步按鈕；交易明細的可信帳戶授權保護維持啟用。
有間 YOUROOM · 2026/10/30
公司訂單同步與商品配對
公司 API 已由雲主機驗證可用。正式訂單同步以新會員註冊為起點，不預先批次匯入未註冊手機的訂單。
觸發與會員身分
- 手機會員註冊成功時，在同一個資料庫交易加入該會員的同步任務。
- 排程約每 2 分鐘檢查任務，由後端讀取會員手機，以 POST JSON 呼叫公司訂單 API。瀏覽器不能指定其他手機。
- 初次讀取最近 10 天與來源最新 10 筆，依公司訂單號去重；已成功同步會員約每 15 分鐘更新一次。
- 手機尚未驗證時可以排入後端同步，但不向會員回傳公司訂單明細。需簡訊驗證後的可信授權程序，或公司管理員獨立核對身分後建立會員綁定。商城目前未提供簡訊服務或自動公司身分驗證。
本商城 API
所有介面使用安全 Cookie 會話、禁止快取。POST 同時檢查同源 Origin 與 X-CSRF-Token。無公開 Bearer 管理員介面；來源 API 金鑰不傳給前端。
| 方法與路徑 | 用途 |
|---|
| GET /api/me/order-identity | 目前會員的手機、公司綁定與同步狀態。 |
| GET /api/me/company-orders?role=buyer | 代付購買訂單；role=seller 為代收銷售訂單。每頁 50 筆，使用回傳 nextCursor 作為 cursor 查下一頁。 |
| GET /api/me/company-orders/{orderId} | 所屬訂單明細、商品配對與最近 20 次變更紀錄。無權存取回傳 404。 |
| POST /api/me/company-sync | JSON 空物件，為目前登入會員排入同步。回傳 202。每會員 15 分鐘最多 2 次。 |
未完成公司綁定時，列表回傳 access: binding_required、空 orders 及本人同步狀態，不洩漏來源訂單數量、金額或資料。已授權則回傳 access: authorized。
類型與來源狀態
| 來源欄位 | 商城行為 |
|---|
| order_type = 1 代收 | 會員為賣家，列入公司銷售訂單。 |
| order_type = 2 代付 | 會員為買家，列入公司購買訂單。 |
| order_status = 1 / 3 / 91 | 原樣對應已配對／已完成／收款超時。未知狀態保留代碼，不推定已付款。 |
商品配對
來源金額以十進位字串精確轉換成分，不對付款金額四捨五入。以現有商品目錄的整數台幣參考價格配對，一種商品最多 20 件；先搜尋單項與兩項組合，再執行有預算上限的多項精確搜尋。合計必須完全相等。不調價、不新增補差商品、不宣稱庫存已保留。
matched 為已配對；no_match、search_limit、fractional_amount 分別代表未找到、達搜尋範圍、來源含非整數台幣。商品行保留 productId、name、specification、unitPriceMinor、quantity、lineTotalMinor、source、referenceOnly。
同訂單、同來源內容不重複建立。只改狀態會保留既有商品組合；金額或代收／代付類型更正時重新配對並保存版本。較舊來源更新不覆寫新版本。公司付款完成不會自動產生物流、成交證明、退款或提領入帳。
資料保護與限制
不匯入來源銀行帳號、銀行代碼或轉帳後五碼。只保存訂單識別、手機對應、金額、類型、狀態、時間、配對與變更快照。查詢以登入會員建立資料庫交易上下文，並使用 PostgreSQL RLS 隔離。
來源沒有更新游標或正式分頁，日期是否按建立或更新篩選尚待供應方確認。因此目前涵蓋最近 10 天與來源最新 10 筆，不宣稱完整歷史已同步；較早訂單的後續變更可能漏掉。幣別暫依本次業務需求設定為 TWD，來源未提供幣別欄位。
金鑰存於 root-only 0600 憑證檔，僅透過 systemd LoadCredential 提供給獨立同步服務；網站 API 不持有來源金鑰。新註冊會員會觸發來源讀取；沒有任務及既有同步會員時，排程不呼叫來源 API。
手機註冊與登入 API · 返回會員中心
會員手機更正與訂單歸屬
公司查詢使用目前會員手機；匯入後以穩定會員UUID保存歸屬。管理員更正手機不會把歷史訂單轉給舊號碼後續註冊者。修改後保留原審核狀態與既有授權，舊號碼的排隊／執行中工作停止，重新建立的日期工作固定保存當時查詢號碼。來源API與本站的手機資料不會互相改寫；若正在同步，請完成後再更正手機。
管理員更正會員手機
更正後自動排入新手機的全部可取得訂單同步，使用來源訂單編號去重並維持會員 UUID 歸屬。舊訂單、配送與生成對話保留；進度及結果在管理員手機修改紀錄與會員訂單同步紀錄查看。來源 API 不完整回應會明確標為失敗。