巡攤 Stall Walk 設計定案

grill-me 設計訪談的全部定案，實作依據。2026-10-06 第 1–5 輪（Q1–Q62），訪談完成。

一、定位與基礎

Q1名稱 巡攤 / Stall Walk，repo 與命名空間 stall-walk。
Q26圖示：候選 01 攤篷（磚紅底、白色遮雨棚與櫃台、虛線步道）。
Q2Repo：Gitea 個人帳號、私有、MIT。gitea.jsc.idv.tw/jiantw83/stall-walk
Q3單人工具，跑在使用者的 WSL 本機，瀏覽器開 localhost 操作。
Q4前端 Vue 3 + TS + Vite + Tailwind + shadcn-vue，SPA embed 進 Go 單一二進位。
Q29支援網頁版與手機版（響應式）。
Q18僅繁體中文。
Q25平台只做蝦皮，不預留多平台。
Q20交付順序：名稱/圖示/repo → UI 預覽（五風格）→ 0 骨架（Go + SQLite + 前端殼 + 備份還原）→ A 賣家追蹤與去重 → B 系列追蹤 → C 批次購物車。
Q19測試：解析器以錄製的頁面/JSON 快照做單元測試；整合測試起 Go 服務對 SQLite 跑排程、去重、備份還原；真蝦皮只做手測，每階段啟動系統給使用者驗。

二、資料採集

事實（2026-10-06 查證）

沒有買家端官方 API；Open Platform 只給賣家，Affiliate GraphQL 只讀 offer。shopee.tw 的 /api/v4/* 未登入一律 403（is_login:false），登入後請求需頁面 JS SDK 簽出的 af-ac-enc-sz-token、x-sap-ri 等標頭，Go 直接發 HTTP 無法重現。服務條款（2026-06-30 版）3.1 禁自動化存取、6.2(k) 禁非官方客戶端、5.3 可因異常大量購買停權；未查到買家因購物車自動化被停權的公開案例。商品規格在 item.models[]（model_id、價格、庫存、tier_index）；購物車以 (shop_id, item_id, model_id) 為單位。官方「關注店家」只有 App 推播，無 Email/RSS。BJ4 動漫宣布明年起退出蝦皮。

賣場	shop_id
BJ4 動漫	3187737
買動漫商城	289652136
墊腳石購物網	20570968
Little d💕小點心漫畫工作室 ◆1店◇	6230030
Zfong 智豐	494379953

Q21引擎：Go 以 chromedp/go-rod 驅動 Chromium（獨立 profile 目錄存登入狀態），在賣場頁面內讓頁面 JS 發請求，以 CDP Network 事件攔截回應 JSON，不解析 DOM、不自組請求。
Q21 Q30新品段：每家賣場依上架時間新到舊翻頁，連續遇到 3 個已知 item_id 才停。
Q30複查段：只對「待購清單 + 系列命中 + 購物車佇列」中的商品打商品頁，更新價格/庫存、偵測失效；價格歷史只對這些商品累積。
Q12價格與庫存歷史每日採樣，預設保留 180 天。
Q34賣場分類為盡力而為：商品資料本身帶分類就存，否則只用系統分類。
Q13 Q39排程每日 07:00 Asia/Taipei，系統內可改；錯過則系統啟動後 5 分鐘補跑；有「手動立即執行」。
Q23失敗降級：驗證碼、「請下載 App」攔截頁、session 失效 → 重試一次後中止，首頁顯示紅色「需要人工處理」，遠端瀏覽器帶到前景，處理完按「繼續」。
Q24Affiliate API 第一版不納入。
Q32每次執行保留追蹤紀錄：網頁操作、請求與回覆、截圖。每日任務全部成功則刪除該次紀錄，否則保留 30 天。

三、登入與遠端瀏覽器

Q17登入兩種：系統內「登入」頁開受控瀏覽器讓使用者手動登入（含簡訊驗證）；或匯入 cookie。cookie 失效時首頁顯示「需重新登入」。
Q35cookie 匯入收 Netscape cookies.txt 與 Cookie-Editor JSON，匯入後寫進 profile，之後以 profile 為準。
Q32遠端瀏覽器呈現：CDP Screencast 把 Chromium 畫面串進系統頁面、滑鼠鍵盤事件回傳（任何裝置含手機可操作，Chromium 可 headless）；設定頁有「除錯模式」改以 WSLg 開有頭視窗。
Q22結帳終點：系統批次加入購物車後，在遠端瀏覽器開蝦皮結帳頁交給使用者人工確認付款。

四、標籤、分類、去重

Q5分類兩層：匯入賣場分類作參考；系統分類（第一版單層）手動指派，為跨賣家分組主力。
Q6自動標籤 = 商品名稱去促銷詞（預購、現貨、免運、特價…，設定頁維護清單）、統一全半形與空白、保留卷數；系統以相似度（trigram）列疑似同品供一鍵合併；合併結果為「別名 → 標準標籤」對應表，新品自動套用。
Q7多選項商品：每個選項獨立，標籤 = 商品名稱 + 選項名稱。
Q8優先賣家：全域預設順序 + 標籤級覆寫。
Q38價低優先只比商品單價（不含運費、優惠券），同價取先上架者；優先賣家缺貨自動退到下一順位，卡片標「優先賣家缺貨」。
Q9去重落選者折疊在勝出者底下，可展開比價、手動改選。
Q31失效重找：商品頁回不存在 → 同賣場以正規化名稱搜尋；正規化「名稱+選項」完全相同即自動接回新 id、歷史延續、標「已重新連結」；相似度 ≥ 0.85 列「待確認重找」；都沒有標「失效」，可手動搜尋重找或切換其他賣家候選。

五、系列追蹤（B）

Q11系列 = 關鍵字規則（多關鍵字 AND、可設排除詞），比對正規化標籤（含選項名），新卷出現自動納入。
Q10「更新」= 任一追蹤賣家出現新的符合系列的商品/選項（價格與庫存變動由複查段處理，不算系列更新）。
Q37規則建立或修改時立即回溯比對既有商品；系列頁依卷數/選項排序，缺卷灰格（從選項名抽數字）。

六、今日巡攤（滑動）與待購清單

Q28右滑「保留」= 放入待購清單；左滑「已讀」= 不再出現但資料保留，可在商品總覽翻回。滑動不觸發瀏覽器動作。
Q29一張卡 = 一個去重後勝出商品/選項，卡上「另 N 家」可展開比價；桌面用 ← → 與拖曳，手機手勢；Undo 深度 10；卡堆 = 所有未處理新品，依賣家優先序與時間排序，頂部顯示剩餘張數；有「全部已讀」與「依賣家/分類批次已讀」。
Q33批次購物車：對待購清單選定項目依序在商品頁由頁面 JS 加入購物車（每筆隨機間隔 2–5 秒）→ 讀回購物車比對 → 結果表（成功/缺貨/失敗）→ 一鍵在遠端瀏覽器開購物車頁結帳 → 使用者按「已下單」，該批移到「已購買」。數量預設 1 可改；不依賣家拆單，保留「只結這家」篩選。

七、通知、備份、設定

Q14 Q27通知走 Synology Chat 傳入 Webhook（設定頁填 URL、可測試）。每日採集完送一則摘要（各賣家新品數、系列命中數、失效數、「開啟今日巡攤」連結，連結基底可改成 LAN 位址）；「需人工處理」即時另送一則；不逐商品推送。
Q15商品圖片下載快取到本機資料夾，記路徑。
Q16備份：「立即備份」+ 每日自動；SQLite VACUUM INTO + 圖片資料夾打包 zip，保留 14 份；還原上傳 zip 覆蓋後重啟。JSON 匯出入作為設定可攜。第一版不做外部清單匯入。
Q36備份預設不含瀏覽器 profile，備份頁可勾「包含登入狀態」並提示風險。

八、頁面與 UI 預覽

Q40十頁：首頁/儀表板、今日巡攤（滑動）、商品總覽、賣家、標籤與分類、系列、待購清單與結帳、遠端瀏覽器、設定、採集紀錄。
Q41 Q62UI 風格五候選（夜市攤、帳本、工具台、雜誌、終端）各做十頁桌面+手機預覽；定案 1 夜市攤：深底暖光、磚紅與沙金強調、卡片如攤位燈箱、Noto Serif TC 標題；預覽 artifact，repo docs/ui-preview/night-market.html 為實作視覺基準。其他四種保留於同目錄。
Q42UI 預覽 HTML 進 repo docs/ui-preview/。

九、第 3–4 輪定案（Q43–Q61）

Q43Repo 維持個人帳號 jiantw83/stall-walk，Go 模組 gitea.jsc.idv.tw/jiantw83/stall-walk。
Q44服務綁 0.0.0.0；非本機存取需系統密碼（初次設定建立，session cookie 30 天）；localhost 免密碼。
Q45 Q57 Q60系統本身只跑 HTTP；對外由 Traefik 以既有 *.jsc.idv.tw 萬用憑證提供 HTTPS，TLS 於上線時補齊。系統不內建 ACME。
Q56主機名稱 stall-walk.jsc.idv.tw。
Q58開發期不用真實手機連線，只以瀏覽器裝置模式驗行動版 UI；不改 WSL 網路模式。
Q59對外 443 + 80（80 重導）由 Traefik 負責；系統監聽埠預設 8080。
Q61PWA 只做安裝（manifest + 圖示 + 外殼快取），離線顯示「離線」頁。
Q46stall-walk install 註冊 systemd user service（WSL 已啟用 systemd）；文件說明 Windows 端讓 WSL 開機常駐。
Q47子指令：serve（預設）、run、backup、restore <zip>、install/uninstall、passwd、version。config.toml（port、bind、資料目錄、時區、排程、trusted_proxies）+ 環境變數覆寫；其餘設定存 SQLite。資料目錄預設 ./data/：stall-walk.db、images/、profile/、traces/、backups/。
Q48追蹤紀錄：每次執行一個 run id，記時間軸事件、攔截到的請求/回覆 JSON、關鍵步驟截圖；採集紀錄頁可展開時間軸、放大截圖、下載 zip。批次購物車/結帳的 run 一律保留 30 天；trace 刪除後 run 摘要列永久保留。
Q49遠端瀏覽器：Chromium 桌面視口 1280×900、桌面 UA；串流 JPEG 品質 60、最高 10 fps、閒置 1 fps；手機可雙指縮放；另有文字輸入框送進頁面焦點元件。
Q50商品列永久保留；已讀且未進待購/系列者圖片 90 天後清除，需要時按需重抓。
Q51初始不設優先賣家，純價低優先；賣家頁拖曳後生效。
Q52「已下單」回填系列卷數為「已擁有」；缺卷與已擁有不同色；可手動勾已擁有。
Q53待購清單項目標「降價 ↓N%」「補貨」徽章；每日摘要加「待購 N 項降價、M 項補貨」。
Q54 Q55UI 預覽：每風格一個 artifact，十頁桌面 + 手機全做；範例資料用真實連載書名、五家賣場名、合理台幣價格並標明為範例。

十、實作預設（不影響使用方式，可翻看）

經 Traefik 進來的請求依 trusted_proxies 讀 X-Forwarded-For 判定為遠端 → 需密碼；只有真正的 loopback 直連免密碼。
新增賣家：貼賣場網址或 shop_id，系統以受控瀏覽器讀取賣場資料確認；移除賣家 = 停用並保留資料。
採集一家一家依序跑，不並行；每日備份在採集完成後（預設 07:30）。
SQLite 以 WAL 模式、內嵌 SQL 遷移（版本表）；日誌 JSON 行格式，檔案輪替保留 14 天。
卷數抽取：從選項/名稱抽「第N集 / N / Vol.N / 第N卷 / (N)」，統一為整數；促銷詞預設清單：預購、現貨、免運、特價、限量、首刷、附贈品、新品、現貨供應、再版。
相似度建議用 SQLite FTS5 trigram；自動合併門檻 1.0（完全相同），建議門檻 0.85。